@cregis-dev/cckit 0.4.0 → 0.5.0

package/templates/bmad/tea/testarch/knowledge/overview.md

@@ -1,286 +0,0 @@
-# Playwright Utils Overview
-
-## Principle
-
-Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
-
-## Rationale
-
-Writing Playwright utilities from scratch for every project leads to:
-
-- Duplicated code across test suites
-- Inconsistent patterns and quality
-- Maintenance burden when Playwright APIs change
-- Missing advanced features (schema validation, HAR recording, auth persistence)
-
-`@seontechnologies/playwright-utils` provides:
-
-- **Production-tested utilities**: Used at SEON Technologies in production
-- **Functional-first design**: Core logic as pure functions, fixtures for convenience
-- **Composable fixtures**: Use `mergeTests` to combine utilities
-- **TypeScript support**: Full type safety with generic types
-- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
-- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
-
-## Installation
-
-```bash
-npm install -D @seontechnologies/playwright-utils
-```
-
-**Peer Dependencies:**
-
-- `@playwright/test` >= 1.54.1 (required)
-- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
-- `zod` >= 3.0.0 (optional - for Zod schema validation)
-
-## Available Utilities
-
-### Core Testing Utilities
-
-| Utility                    | Purpose                                                                       | Test Context       |
-| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
-| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
-| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
-| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
-| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
-| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
-| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
-| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
-| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
-| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
-
-**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
-
-## Design Patterns
-
-### Pattern 1: Functional Core, Fixture Shell
-
-**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
-
-**Implementation**:
-
-```typescript
-// Direct import (pass Playwright context explicitly)
-import { apiRequest } from '@seontechnologies/playwright-utils';
-
-test('direct usage', async ({ request }) => {
-  const { status, body } = await apiRequest({
-    request, // Must pass request context
-    method: 'GET',
-    path: '/api/users',
-  });
-});
-
-// Fixture import (context injected automatically)
-import { test } from '@seontechnologies/playwright-utils/fixtures';
-
-test('fixture usage', async ({ apiRequest }) => {
-  const { status, body } = await apiRequest({
-    // No need to pass request context
-    method: 'GET',
-    path: '/api/users',
-  });
-});
-```
-
-**Key Points**:
-
-- Pure functions testable without Playwright running
-- Fixtures inject framework dependencies automatically
-- Choose direct import (more control) or fixture (convenience)
-
-### Pattern 2: Subpath Imports for Tree-Shaking
-
-**Context**: Import only what you need to keep bundle sizes small.
-
-**Implementation**:
-
-```typescript
-// Import specific utility
-import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
-
-// Import specific fixture
-import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
-
-// Import everything (use sparingly)
-import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
-```
-
-**Key Points**:
-
-- Subpath imports enable tree-shaking
-- Keep bundle sizes minimal
-- Import from specific paths for production builds
-
-### Pattern 3: Fixture Composition with mergeTests
-
-**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
-
-**Implementation**:
-
-```typescript
-// playwright/support/merged-fixtures.ts
-import { mergeTests } from '@playwright/test';
-import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
-import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
-import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
-import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
-
-// Merge all fixtures into one test object
-export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
-
-export { expect } from '@playwright/test';
-```
-
-```typescript
-// In your tests
-import { test, expect } from '../support/merged-fixtures';
-
-test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
-  await log.step('Making authenticated API request');
-
-  const { body } = await apiRequest({
-    method: 'GET',
-    path: '/api/protected',
-    headers: { Authorization: `Bearer ${authToken}` },
-  });
-
-  await recurse(
-    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
-    (res) => res.body.ready === true,
-  );
-});
-```
-
-**Key Points**:
-
-- `mergeTests` combines multiple fixtures without conflicts
-- Create one merged-fixtures.ts file per project
-- Import test object from your merged fixtures in all tests
-- All utilities available in single test signature
-
-## Integration with Existing Tests
-
-### Gradual Adoption Strategy
-
-**1. Start with logging** (zero breaking changes):
-
-```typescript
-import { log } from '@seontechnologies/playwright-utils';
-
-test('existing test', async ({ page }) => {
-  await log.step('Navigate to page'); // Just add logging
-  await page.goto('/dashboard');
-  // Rest of test unchanged
-});
-```
-
-**2. Add API utilities** (for API tests):
-
-```typescript
-import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
-
-test('API test', async ({ apiRequest }) => {
-  const { status, body } = await apiRequest({
-    method: 'GET',
-    path: '/api/users',
-  });
-
-  expect(status).toBe(200);
-});
-```
-
-**3. Expand to network utilities** (for UI tests):
-
-```typescript
-import { test } from '@seontechnologies/playwright-utils/fixtures';
-
-test('UI with network control', async ({ page, interceptNetworkCall }) => {
-  const usersCall = interceptNetworkCall({
-    url: '**/api/users',
-  });
-
-  await page.goto('/dashboard');
-  const { responseJson } = await usersCall;
-
-  expect(responseJson).toHaveLength(10);
-});
-```
-
-**4. Full integration** (merged fixtures):
-
-Create merged-fixtures.ts and use across all tests.
-
-## Related Fragments
-
-- `api-request.md` - HTTP client with schema validation
-- `network-recorder.md` - HAR-based offline testing
-- `auth-session.md` - Token management
-- `intercept-network-call.md` - Network interception
-- `recurse.md` - Polling patterns
-- `log.md` - Logging utility
-- `file-utils.md` - File operations
-- `fixtures-composition.md` - Advanced mergeTests patterns
-
-## Anti-Patterns
-
-**❌ Don't mix direct and fixture imports in same test:**
-
-```typescript
-import { apiRequest } from '@seontechnologies/playwright-utils';
-import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
-
-test('bad', async ({ request, authToken }) => {
-  // Confusing - mixing direct (needs request) and fixture (has authToken)
-  await apiRequest({ request, method: 'GET', path: '/api/users' });
-});
-```
-
-**✅ Use consistent import style:**
-
-```typescript
-import { test } from '../support/merged-fixtures';
-
-test('good', async ({ apiRequest, authToken }) => {
-  // Clean - all from fixtures
-  await apiRequest({ method: 'GET', path: '/api/users' });
-});
-```
-
-**❌ Don't import everything when you need one utility:**
-
-```typescript
-import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
-```
-
-**✅ Use subpath imports:**
-
-```typescript
-import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
-```
-
-## Reference Implementation
-
-The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
-
-**Repository:** <https://github.com/seontechnologies/playwright-utils>
-
-**Key resources:**
-
-- **Test examples:** `playwright/tests` - All utilities in action
-- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
-- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
-
-**Quick start:**
-
-```bash
-git clone https://github.com/seontechnologies/playwright-utils.git
-cd playwright-utils
-nvm use
-npm install
-npm run test:pw-ui  # Explore tests with Playwright UI
-npm run test:pw
-```
-
-All patterns in TEA fragments are production-tested in this repository.

package/templates/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_