bmad-studio 0.1.0 → 0.2.0

package/_bmad/tea/testarch/knowledge/pact-mcp.md

@@ -1,204 +0,0 @@
-# Pact MCP Server (SmartBear)
-
-## Principle
-
-Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
-
-## Rationale
-
-### Why MCP for contract testing?
-
-- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
-- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
-- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
-- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
-
-### When TEA uses it
-
-- **test-design workflow**: Fetch existing provider states to understand current contract landscape
-- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
-- **test-review workflow**: Review pact tests against best practices with automated feedback
-- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
-
-## Available Tools
-
-| #   | Tool                      | Description                                                             | When Used             |
-| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
-| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
-| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
-| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
-| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
-| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
-| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
-| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
-| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
-
-## Installation
-
-### Config file locations
-
-| Tool              | Global Config File                    | Format                 |
-| ----------------- | ------------------------------------- | ---------------------- |
-| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
-| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
-| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
-| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
-| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
-| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
-
-> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
-
-### CLI shortcuts (Claude Code and Codex)
-
-```bash
-# Claude Code — use add-json for servers with env vars (-s user = global)
-claude mcp add-json -s user smartbear \
-  '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-token>"}}'
-
-# Codex
-codex mcp add smartbear -- npx -y @smartbear/mcp@latest
-```
-
-### JSON config (Gemini CLI, Cursor, Windsurf)
-
-Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
-
-```json
-{
-  "mcpServers": {
-    "smartbear": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@smartbear/mcp@latest"],
-      "env": {
-        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
-        "PACT_BROKER_TOKEN": "<your-api-token>"
-      }
-    }
-  }
-}
-```
-
-### Codex TOML config
-
-Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.smartbear]
-command = "npx"
-args = ["-y", "@smartbear/mcp@latest"]
-
-[mcp_servers.smartbear.env]
-PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
-PACT_BROKER_TOKEN = "<your-api-token>"
-```
-
-Note the key is `mcp_servers` (underscored), not `mcpServers`.
-
-### VS Code (GitHub Copilot)
-
-Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
-
-```json
-{
-  "servers": {
-    "smartbear": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@smartbear/mcp@latest"],
-      "env": {
-        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
-        "PACT_BROKER_TOKEN": "${input:pactToken}"
-      }
-    }
-  }
-}
-```
-
-> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
-
-## Required Environment Variables
-
-| Variable               | Required                     | Description                             |
-| ---------------------- | ---------------------------- | --------------------------------------- |
-| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
-| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
-| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
-| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
-
-**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
-
-**Requirements**: Node.js 20+
-
-## Pattern Examples
-
-### Example 1: Fetching Provider States During Test Design
-
-When designing contract tests, use MCP to query existing provider states:
-
-```
-# Agent queries SmartBear MCP during test-design workflow:
-# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
-# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
-#
-# Agent uses this to generate comprehensive consumer tests covering all states
-```
-
-### Example 2: Reviewing Pact Tests
-
-During test-review workflow, use MCP to evaluate test quality:
-
-```
-# Agent submits test file to SmartBear MCP Review tool:
-# → Review Pact Tests with test file content
-# ← Returns: feedback on matcher usage, state coverage, interaction naming
-#
-# Agent incorporates feedback into review report
-```
-
-### Example 3: Can I Deploy Check in CI
-
-During CI workflow design, reference the can-i-deploy tool:
-
-```
-# Agent generates CI pipeline with can-i-deploy gate:
-# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
-# ← Returns: { ok: true/false, reason: "..." }
-#
-# Agent designs pipeline to block deployment if can-i-deploy fails
-```
-
-## Key Points
-
-- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
-- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
-- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
-- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
-- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
-
-## Related Fragments
-
-- `pactjs-utils-overview.md` — runtime utilities that pact tests import
-- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
-- `contract-testing.md` — foundational contract testing patterns
-
-## Anti-Patterns
-
-### Wrong: Using MCP for runtime test execution
-
-```
-# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
-# MCP is for agent-assisted design, generation, and review
-```
-
-### Right: Use MCP for design-time assistance
-
-```
-# ✅ Use MCP during planning and review:
-# - Fetch provider states to inform test design
-# - Generate test scaffolds from existing contracts
-# - Review tests for best practice compliance
-# - Check can-i-deploy during CI pipeline design
-```
-
-_Source: SmartBear MCP documentation, PactFlow developer docs_

package/_bmad/tea/testarch/knowledge/pactjs-utils-consumer-helpers.md

@@ -1,270 +0,0 @@
-# Pact.js Utils Consumer Helpers
-
-## Principle
-
-Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
-
-## Rationale
-
-### Problems with raw consumer helper handling
-
-- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
-- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
-- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
-- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
-- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
-
-### Solutions
-
-- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
-- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
-- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
-- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
-
-## Pattern Examples
-
-### Example 1: Basic Provider State Creation
-
-```typescript
-import { PactV3, MatchersV3 } from '@pact-foundation/pact';
-import { createProviderState } from '@seontechnologies/pactjs-utils';
-
-const provider = new PactV3({
-  consumer: 'movie-web',
-  provider: 'SampleMoviesAPI',
-  dir: './pacts',
-});
-
-describe('Movie API Contract', () => {
-  it('should return movie by id', async () => {
-    // createProviderState returns [stateName, JsonMap] tuple
-    const providerState = createProviderState({
-      name: 'movie with id 1 exists',
-      params: { id: 1, name: 'Inception', year: 2010 },
-    });
-
-    await provider
-      .given(...providerState) // Spread tuple into .given(name, params)
-      .uponReceiving('a request for movie 1')
-      .withRequest({ method: 'GET', path: '/movies/1' })
-      .willRespondWith({
-        status: 200,
-        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
-      })
-      .executeTest(async (mockServer) => {
-        const res = await fetch(`${mockServer.url}/movies/1`);
-        const movie = await res.json();
-        expect(movie.name).toBe('Inception');
-      });
-  });
-});
-```
-
-**Key Points**:
-
-- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
-- Both `name` and `params` are required (pass `params: {}` for states without parameters)
-- Returns `[string, JsonMap]` — spread with `...` into `.given()`
-- `params` values are automatically converted to JsonMap-compatible types
-- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
-
-### Example 2: Complex Parameters with toJsonMap
-
-```typescript
-import { toJsonMap } from '@seontechnologies/pactjs-utils';
-
-// toJsonMap conversion rules:
-// - string, number, boolean → passed through
-// - null → "null" (string)
-// - undefined → "null" (string, same as null)
-// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
-// - nested object → JSON string
-// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
-
-const params = toJsonMap({
-  id: 42,
-  name: 'John Doe',
-  active: true,
-  score: null,
-  createdAt: new Date('2025-01-15T10:00:00Z'),
-  metadata: { role: 'admin', permissions: ['read', 'write'] },
-});
-
-// Result:
-// {
-//   id: 42,
-//   name: "John Doe",
-//   active: true,
-//   score: "null",
-//   createdAt: "2025-01-15T10:00:00.000Z",
-//   metadata: '{"role":"admin","permissions":["read","write"]}'
-// }
-```
-
-**Key Points**:
-
-- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
-- Use it when you need explicit control over parameter conversion outside of provider states
-- Conversion rules are deterministic: same input always produces same output
-
-### Example 3: Provider State Without Parameters
-
-```typescript
-import { createProviderState } from '@seontechnologies/pactjs-utils';
-
-// State without params — second tuple element is empty object
-const emptyState = createProviderState({ name: 'no movies exist', params: {} });
-// Returns: ['no movies exist', {}]
-
-await provider
-  .given(...emptyState)
-  .uponReceiving('a request when no movies exist')
-  .withRequest({ method: 'GET', path: '/movies' })
-  .willRespondWith({ status: 200, body: [] })
-  .executeTest(async (mockServer) => {
-    const res = await fetch(`${mockServer.url}/movies`);
-    const movies = await res.json();
-    expect(movies).toEqual([]);
-  });
-```
-
-### Example 4: Multiple Provider States
-
-```typescript
-import { createProviderState } from '@seontechnologies/pactjs-utils';
-
-// Some interactions require multiple provider states
-// Call .given() multiple times with different states
-await provider
-  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
-  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
-  .uponReceiving('an authenticated request for movie 5')
-  .withRequest({
-    method: 'GET',
-    path: '/movies/5',
-    headers: { Authorization: MatchersV3.like('Bearer token') },
-  })
-  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
-  .executeTest(async (mockServer) => {
-    // test implementation
-  });
-```
-
-### Example 5: When to Use setJsonBody vs setJsonContent
-
-```typescript
-import { MatchersV3 } from '@pact-foundation/pact';
-import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
-
-const { integer, string } = MatchersV3;
-
-await pact
-  .addInteraction()
-  .given('movie exists')
-  .uponReceiving('a request to get movie by name')
-  .withRequest(
-    'GET',
-    '/movies',
-    setJsonContent({
-      query: { name: 'Inception' },
-      headers: { Accept: 'application/json' },
-    }),
-  )
-  .willRespondWith(
-    200,
-    setJsonBody({
-      status: 200,
-      data: { id: integer(1), name: string('Inception') },
-    }),
-  );
-```
-
-**Key Points**:
-
-- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
-- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
-- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
-
-## Key Points
-
-- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
-- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
-- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
-- **Date handling**: Date objects become ISO 8601 strings
-- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
-- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
-- **Message pacts**: Works identically with `MessageConsumerPact` — same `.given()` API
-- **Builder reuse**: `setJsonContent` works for both `.withRequest(...)` and `.willRespondWith(...)` callbacks (query is ignored on response builders)
-- **Body shorthand**: `setJsonBody` keeps body-only responses concise and readable
-- **Matchers check type, not value**: `string('My movie')` means "any string", `integer(1)` means "any integer". The example values are arbitrary — the provider can return different values and verification still passes as long as the type matches. Use matchers only in `.willRespondWith()` (responses), never in `.withRequest()` (requests) — Postel's Law applies.
-- **Reuse test values across files**: Interactions are uniquely identified by `uponReceiving` + `.given()`, not by placeholder values. Two test files can both use `testId: 100` without conflicting. On the provider side, shared values simplify state handlers — idempotent handlers (check if exists, create if not) only need to ensure one record exists. Use different values only when testing different states of the same entity type (e.g., `movieExists(100)` for happy paths vs. `movieNotFound(999)` for error paths).
-
-## Related Fragments
-
-- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
-- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
-- `contract-testing.md` — foundational patterns with raw Pact.js
-
-## Anti-Patterns
-
-### Wrong: Manual JsonMap assembly
-
-```typescript
-// ❌ Manual casting — verbose, error-prone, no type safety
-provider.given('user exists', {
-  id: 1 as unknown as string,
-  createdAt: new Date().toISOString(),
-  metadata: JSON.stringify({ role: 'admin' }),
-} as JsonMap);
-```
-
-### Right: Use createProviderState
-
-```typescript
-// ✅ Automatic conversion with type safety
-provider.given(
-  ...createProviderState({
-    name: 'user exists',
-    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
-  }),
-);
-```
-
-### Wrong: Inline state names without helper
-
-```typescript
-// ❌ Duplicated state names between consumer and provider — easy to mismatch
-provider.given('a user with id 1 exists', { id: '1' });
-// Later in provider: 'user with id 1 exists' — different string!
-```
-
-### Right: Share state constants
-
-```typescript
-// ✅ Define state names as constants shared between consumer and provider
-const STATES = {
-  USER_EXISTS: 'user with id exists',
-  NO_USERS: 'no users exist',
-} as const;
-
-provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
-```
-
-### Wrong: Repeating inline builder lambdas everywhere
-
-```typescript
-// ❌ Repetitive callback boilerplate in every interaction
-.willRespondWith(200, (builder) => {
-  builder.jsonBody({ status: 200 });
-});
-```
-
-### Right: Use setJsonBody / setJsonContent
-
-```typescript
-// ✅ Reusable callbacks with less boilerplate
-.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
-.willRespondWith(200, setJsonBody({ status: 200 }));
-```
-
-_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_

package/_bmad/tea/testarch/knowledge/pactjs-utils-overview.md

@@ -1,216 +0,0 @@
-# Pact.js Utils Overview
-
-## Principle
-
-Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
-
-## Rationale
-
-### Problems with raw @pact-foundation/pact
-
-- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
-- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
-- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
-- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
-- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
-- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
-- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
-
-### Solutions from pactjs-utils
-
-- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
-- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
-- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
-- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
-- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
-- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
-- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
-- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
-- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
-- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
-
-## Installation
-
-```bash
-npm install -D @seontechnologies/pactjs-utils
-
-# Peer dependency
-npm install -D @pact-foundation/pact
-```
-
-**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
-
-## Available Utilities
-
-| Category          | Function                          | Description                                          | Use Case                                                         |
-| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
-| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
-| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
-| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
-| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
-| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
-| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
-| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
-| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
-| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
-
-## Decision Tree: Which Flow?
-
-```
-Is this a monorepo (consumer + provider in same repo)?
-├── YES → Local Flow
-│   - Consumer generates pact files to ./pacts/
-│   - Provider reads pact files from ./pacts/ (no broker needed)
-│   - Use buildVerifierOptions with pactUrls option
-│
-└── NO → Do you have a Pact Broker / PactFlow?
-    ├── YES → Remote (CDCT) Flow
-    │   - Consumer publishes pacts to broker
-    │   - Provider verifies from broker
-    │   - Use buildVerifierOptions with broker config
-    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
-    │
-    └── Do you have an OpenAPI spec?
-        ├── YES → BDCT Flow (PactFlow only)
-        │   - Provider publishes OpenAPI spec to PactFlow
-        │   - PactFlow cross-validates consumer pacts against spec
-        │   - No provider verification test needed
-        │
-        └── NO → Start with Local Flow, migrate to Remote later
-```
-
-## Design Philosophy
-
-1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
-2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
-3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
-4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
-5. **Composable**: Utilities work independently — use only what you need
-
-## Pattern Examples
-
-### Example 1: Minimal Consumer Test
-
-```typescript
-import { PactV3 } from '@pact-foundation/pact';
-import { createProviderState } from '@seontechnologies/pactjs-utils';
-
-const provider = new PactV3({
-  consumer: 'my-frontend',
-  provider: 'my-api',
-  dir: './pacts',
-});
-
-it('should get user by id', async () => {
-  await provider
-    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
-    .uponReceiving('a request for user 1')
-    .withRequest({ method: 'GET', path: '/users/1' })
-    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
-    .executeTest(async (mockServer) => {
-      const res = await fetch(`${mockServer.url}/users/1`);
-      expect(res.status).toBe(200);
-    });
-});
-```
-
-### Example 2: Minimal Provider Verification
-
-```typescript
-import { Verifier } from '@pact-foundation/pact';
-import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
-
-const opts = buildVerifierOptions({
-  provider: 'my-api',
-  port: '3001',
-  includeMainAndDeployed: true,
-  stateHandlers: {
-    'user exists': async (params) => {
-      await db.seed({ users: [{ id: params?.id }] });
-    },
-  },
-  requestFilter: createRequestFilter({
-    tokenGenerator: () => 'test-token-123',
-  }),
-});
-
-await new Verifier(opts).verifyProvider();
-```
-
-## Key Points
-
-- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
-- **Peer dependency**: `@pact-foundation/pact` must be installed separately
-- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
-- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
-- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
-- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
-- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
-
-## Related Fragments
-
-- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
-- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
-- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
-- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
-- `test-levels-framework.md` — where contract tests fit in the testing pyramid
-
-## Anti-Patterns
-
-### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
-
-```typescript
-// ❌ Don't assemble VerifierOptions manually
-const opts: VerifierOptions = {
-  provider: 'my-api',
-  providerBaseUrl: 'http://localhost:3001',
-  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
-  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
-  publishVerificationResult: process.env.CI === 'true',
-  providerVersion: process.env.GIT_SHA || 'dev',
-  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
-  stateHandlers: {
-    /* ... */
-  },
-  requestFilter: (req, res, next) => {
-    /* ... */
-  },
-  // ... 20 more lines
-};
-```
-
-### Right: Use buildVerifierOptions
-
-```typescript
-// ✅ Single call handles all configuration
-const opts = buildVerifierOptions({
-  provider: 'my-api',
-  port: '3001',
-  includeMainAndDeployed: true,
-  stateHandlers: {
-    /* ... */
-  },
-  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
-});
-```
-
-### Wrong: Importing raw Pact types for JsonMap conversion
-
-```typescript
-// ❌ Manual JsonMap casting
-import type { JsonMap } from '@pact-foundation/pact';
-
-provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
-```
-
-### Right: Use createProviderState
-
-```typescript
-// ✅ Automatic type conversion
-import { createProviderState } from '@seontechnologies/pactjs-utils';
-
-provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
-```
-
-_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_