bmad-studio 0.1.0

package/_bmad/tea/testarch/knowledge/pactjs-utils-provider-verifier.md

@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+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 || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_

package/_bmad/tea/testarch/knowledge/pactjs-utils-request-filter.md

@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_