@cregis-dev/cckit 0.3.0 → 0.4.0

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

@@ -0,0 +1,211 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState` and `toJsonMap` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples for consumer contract tests. These helpers eliminate manual `JsonMap` casting and ensure consistent parameter serialization across all consumer pact interactions.
+
+## Rationale
+
+### Problems with raw provider state 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
+
+### 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
+
+## 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
+  });
+```
+
+## 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
+
+## 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 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_

package/templates/bmad/tea/testarch/knowledge/pactjs-utils-overview.md

@@ -0,0 +1,210 @@
+# 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, 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
+- **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)
+- **`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                 |
+| 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)
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState and toJsonMap 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_