specshield 1.0.13 → 2.0.0

package/README.md

@@ -7,17 +7,16 @@
 
 ---
 
-> **OpenAPI Diff · Swagger Diff · API Breaking Change Detection · Contract Testing · Pact Alternative · API Governance · CI/CD API Validation · API Drift Detection**
+> **OpenAPI Diff · Swagger Diff · API Breaking Change Detection · Contract Testing · Pact Alternative · API Governance · CI/CD API Validation · API Drift Detection · Bi-Directional Contract Testing**
 
 ---
 
 ## Stop Breaking APIs in Production
 
-**SpecShield** detects breaking API changes and runs contract tests directly in your CI/CD pipeline —
-before they become production incidents.
+**SpecShield** detects breaking API changes, runs contract tests, and gates deployments — directly in your CI/CD pipeline before they become production incidents.
 
 ```
-OpenAPI diff  +  contract testing  +  deployment gating  —  in one CLI.
+OpenAPI diff  +  contract testing  +  bi-directional contracts  +  GitHub PR checks  —  in one CLI.
 ```
 
 No broker. No complex setup. Works in 30 seconds.
@@ -135,19 +134,21 @@ That's it. Works with any OpenAPI 3.x YAML or JSON spec.
 
 ## Local vs Cloud
 
-| Feature | Local (Free) | Cloud (specshield.io) |
-|---|---|---|
-| Compare two spec files | ✅ | ✅ |
-| Breaking change detection | ✅ | ✅ |
-| JSON / human output | ✅ | ✅ |
-| Fail CI on breaking change | ✅ | ✅ |
-| **Compare history & dashboard** | ❌ | ✅ |
-| **Contract testing registry** | ❌ | ✅ |
-| **can-i-deploy gating** | ❌ | ✅ |
-| **Team collaboration** | ❌ | ✅ |
-| **API drift trends** | ❌ | ✅ |
-
-Local is great for getting started. Cloud is what your team ships with.
+| Feature | Local (Free) | Cloud Free | Cloud Pro |
+|---|---|---|---|
+| Compare two spec files | ✅ | ✅ | ✅ |
+| Breaking change detection | ✅ | ✅ | ✅ |
+| JSON / human output | ✅ | ✅ | ✅ |
+| Fail CI on breaking change | ✅ | ✅ | ✅ |
+| **Compare history & dashboard** | ❌ | ✅ | ✅ |
+| **CDCT contract testing registry** | ❌ | ✅ | ✅ |
+| **CDCT can-i-deploy gating** | ❌ | ✅ | ✅ |
+| **GitHub App PR checks** | ❌ | ✅ | ✅ |
+| **BDCT bi-directional contracts** | ❌ | ❌ | ✅ |
+| **BDCT can-i-deploy gating** | ❌ | ❌ | ✅ |
+| **BDCT compatibility matrix** | ❌ | ❌ | ✅ |
+| **Team collaboration** | ❌ | ❌ | ✅ |
+| **API drift trends** | ❌ | ✅ | ✅ |
 
 ---
 
@@ -190,13 +191,16 @@ Track API drift over time across your entire platform. Know what changed, when,
 
 ## vs. Alternatives
 
-| Feature | SpecShield | Pact | openapi-diff |
+| Feature | SpecShield | Pact / Pactflow | openapi-diff |
 |---|---|---|---|
 | OpenAPI / Swagger native | ✅ | ❌ (code-level) | ✅ |
 | No broker required | ✅ | ❌ (needs Pact Broker) | ✅ |
-| Contract testing | ✅ | ✅ | ❌ |
+| Consumer-driven contract testing | ✅ | ✅ | ❌ |
+| **Bi-directional contract testing** | ✅ | ✅ (Pactflow paid) | ❌ |
 | Breaking change detection | ✅ | ❌ | ✅ |
 | can-i-deploy gating | ✅ | ✅ (via broker) | ❌ |
+| **GitHub App PR checks** | ✅ | ❌ | ❌ |
+| **Pact JSON contract import** | ✅ | ✅ | ❌ |
 | Hosted dashboard | ✅ | ✅ (Pactflow, paid) | ❌ |
 | Team collaboration | ✅ | ✅ (paid) | ❌ |
 | CLI-first workflow | ✅ | ❌ | ✅ |
@@ -208,8 +212,8 @@ Track API drift over time across your entire platform. Know what changed, when,
 
 | Plan | Price | What's included |
 |---|---|---|
-| **Free** | $0 forever | Local compare, unlimited. Cloud: compare history, API keys, dashboard |
-| **Pro** | Coming soon | Team collaboration, advanced reporting, priority support |
+| **Free** | $0 forever | Local compare (unlimited) · Compare history & dashboard · CDCT contracts & can-i-deploy · GitHub App PR checks |
+| **Pro** | Coming soon | Everything in Free + BDCT bi-directional contracts · BDCT can-i-deploy & matrix · Team collaboration · Advanced reporting · Priority support |
 
 No credit card ever required for the free plan.
 **[Get started free →](https://specshield.io)**
@@ -291,14 +295,70 @@ specshield compare base.yaml target.yaml --remote --json --output result.json
 
 ---
 
-## Contract Testing
+## GitHub Integration
+
+**Automatic API contract checks on every pull request — no workflow YAML required.**
+
+Install the SpecShield GitHub App once and every PR that touches your OpenAPI spec gets:
+- A GitHub check run (pass/fail) visible directly on the PR
+- A PR comment with the full diff table — breaking changes highlighted in red
+- Configurable `fail-on-breaking` per repository
+
+### Install the GitHub App
+
+1. Go to **Dashboard → GitHub Integration** at [specshield.io](https://specshield.io)
+2. Click **Install GitHub App**
+3. Choose the repositories to enable (or select all)
+4. Done — no secrets, no workflow changes needed
+
+### How It Works
+
+When a PR is opened or updated, SpecShield:
+
+1. Fetches the OpenAPI spec from the base branch and the PR branch
+2. Runs the same diff engine as `specshield compare`
+3. Posts a GitHub check run — **Passed** if no breaking changes, **Failed** if breaking changes found
+4. Adds a PR comment with the full breakdown:
+
+```
+## SpecShield API Contract Check
+
+| Change | Type | Severity |
+|--------|------|----------|
+| POST /payments — "amount" required field added | Request schema | BREAKING |
+| GET /orders/{id} — "status" type changed | Response schema | BREAKING |
+| GET /users — new query param "filter" | Addition | NON-BREAKING |
+
+Breaking changes: 2 · Non-breaking: 1
+```
+
+### Configure Per Repository
+
+Add a `.specshield.yml` to your repo root:
+
+```yaml
+github:
+  specPath: api/openapi.yaml   # path to your spec (default: openapi.yaml)
+  failOnBreaking: true         # block PR merge on breaking changes (default: true)
+  commentOnPr: true            # post breakdown comment (default: true)
+```
+
+### Requirements
+
+- The spec file must exist on both the base branch and the PR branch
+- Supported formats: OpenAPI 3.x YAML or JSON
+- The GitHub App needs `pull_requests: write` and `checks: write` permissions (granted during install)
+
+---
+
+## Contract Testing (CDCT)
 
 Consumer-driven contract testing for microservices — without a broker.
 
 **How it works:**
 
 1. Consumer team publishes a contract (what they expect from the provider)
-2. Provider team verifies their service satisfies it
+2. Provider team verifies their service satisfies it by actually calling it
 3. `can-i-deploy` gates the deployment based on verification results
 
 ### Contract File Format
@@ -389,7 +449,7 @@ specshield contracts latest --consumer checkout-ui --provider payment-service --
 specshield contracts history --contract-id 42
 ```
 
-### Full Workflow
+### Full CDCT Workflow
 
 ```bash
 # 1. Consumer publishes contract
@@ -404,6 +464,294 @@ specshield contracts can-i-deploy --provider payment-service --version v2.1.0
 
 ---
 
+## Bi-Directional Contract Testing (BDCT)
+
+**Spec-to-spec contract testing — no running services required.**
+
+BDCT is the static alternative to CDCT. Instead of running the provider server, both sides publish their OpenAPI specs. SpecShield compares them and flags mismatches immediately — ideal for teams that don't run services locally or in CI.
+
+> BDCT requires a **Pro plan**. [Upgrade at specshield.io/upgrade](https://specshield.io/upgrade)
+
+**CDCT vs BDCT:**
+
+| | CDCT | BDCT |
+|---|---|---|
+| How verification works | Replay requests against a live server | Compare OpenAPI specs statically |
+| Provider needs to run | Yes | No |
+| Feedback speed | After deploy to test env | Immediately on spec publish |
+| Pact JSON contracts | Supported | Supported (auto-converted) |
+| Best for | Runtime correctness | Early spec-level safety |
+
+### How BDCT Works
+
+1. Consumer team publishes an OpenAPI spec subset (the endpoints they use)
+2. Provider team publishes their full OpenAPI spec
+3. SpecShield compares them: endpoint presence, request schemas, response fields, status codes, types
+4. `can-i-deploy` gates the deployment — returns `0` only when all consumers are compatible
+
+### Publish a Provider Spec
+
+```bash
+specshield bdct publish-provider \
+  --org acme-store \
+  --provider payment-service \
+  --version v2.1.0 \
+  --spec ./api/openapi.yaml \
+  --env production
+```
+
+```
+  ✔  Provider spec published
+     Provider  : payment-service
+     Version   : v2.1.0
+     Env       : production
+     Auto-verifications triggered: 3
+```
+
+### Publish a Consumer Contract
+
+The consumer contract is an OpenAPI spec that describes only the endpoints the consumer uses:
+
+```yaml
+# consumer-contract.yaml — only the subset checkout-ui uses
+openapi: "3.0.0"
+info:
+  title: checkout-ui → payment-service contract
+  version: "1.0.0"
+paths:
+  /payments:
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [orderId, amount, currency]
+              properties:
+                orderId: { type: string }
+                amount:  { type: number }
+                currency: { type: string }
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  paymentId: { type: string }
+                  status:    { type: string }
+```
+
+```bash
+specshield bdct publish-consumer \
+  --org acme-store \
+  --consumer checkout-ui \
+  --provider payment-service \
+  --version 2.0.0 \
+  --contract ./contracts/checkout-ui-payment.yaml
+```
+
+```
+  ✔  Consumer contract published
+     Consumer    : checkout-ui @ 2.0.0
+     Provider    : payment-service
+     Compatibility: COMPATIBLE
+```
+
+If the provider spec is already published, compatibility is checked immediately.
+
+**Pact JSON contracts are also accepted** — SpecShield auto-converts them:
+
+```bash
+specshield bdct publish-consumer \
+  --org acme-store \
+  --consumer checkout-ui \
+  --provider payment-service \
+  --version 2.0.0 \
+  --contract ./pacts/checkout-ui-payment-service.json
+```
+
+### Verify Compatibility
+
+Manually trigger a verification between a specific consumer/provider pair:
+
+```bash
+specshield bdct verify \
+  --org acme-store \
+  --consumer checkout-ui \
+  --consumer-version 2.0.0 \
+  --provider payment-service \
+  --provider-version v2.1.0 \
+  --env production
+```
+
+Compatible output:
+```
+  ✔  COMPATIBLE
+
+  Endpoints checked: 2
+  Compatible       : 2
+  Incompatible     : 0
+```
+
+Incompatible output:
+```
+  ✖  INCOMPATIBLE
+
+  Endpoints checked: 2
+  Compatible       : 1
+  Incompatible     : 1
+
+  Issues
+  ● POST /payments [ERROR] RESPONSE_FIELD_MISSING
+    field: $.status
+    Consumer expects it — provider spec does not return it
+
+  ● GET /payments/{id} [WARNING] TYPE_MISMATCH
+    field: $.amount
+    consumer: integer  →  provider: string
+```
+
+### Can I Deploy? (BDCT)
+
+```bash
+specshield bdct can-i-deploy \
+  --org acme-store \
+  --service payment-service \
+  --version v2.1.0 \
+  --env production
+```
+
+```
+  ✔  DEPLOYABLE
+
+  payment-service v2.1.0 is COMPATIBLE with all 3 consumer(s)
+```
+
+```
+  ✖  NOT DEPLOYABLE
+
+  payment-service v2.1.0 is INCOMPATIBLE with:
+    checkout-ui@2.0.0 (INCOMPATIBLE)
+    mobile-app@1.5.0  (INCOMPATIBLE)
+```
+
+Exit codes: `0` = deployable · `1` = blocked · `2` = error
+
+### Compatibility Matrix
+
+View the compatibility status across all consumer/provider pairs in your org:
+
+```bash
+specshield bdct matrix --org acme-store --env production
+```
+
+```
+  Compatibility Matrix  (env: production)
+
+                    payment-service  order-service
+  checkout-ui       COMPATIBLE       COMPATIBLE
+  mobile-app        INCOMPATIBLE     COMPATIBLE
+  partner-sdk       COMPATIBLE       UNKNOWN
+```
+
+### List Provider Specs
+
+```bash
+# All providers for the org
+specshield bdct list-providers --org acme-store
+
+# Filter by provider name
+specshield bdct list-providers --org acme-store --provider payment-service
+```
+
+```
+  Provider Specs
+
+  payment-service  v2.1.0   production   2025-05-01
+  payment-service  v2.0.0   staging      2025-04-20
+  order-service    v1.3.0   production   2025-04-28
+```
+
+### List Consumer Contracts
+
+```bash
+# All consumers for the org
+specshield bdct list-consumers --org acme-store
+
+# Filter by consumer or provider
+specshield bdct list-consumers --org acme-store --consumer checkout-ui
+specshield bdct list-consumers --org acme-store --provider payment-service
+```
+
+### List Verifications
+
+```bash
+specshield bdct list-verifications \
+  --org acme-store \
+  --provider payment-service \
+  --env production \
+  --page 0 \
+  --size 20
+```
+
+```
+  BDCT Verifications
+
+  Consumer     Consumer Ver  Provider          Provider Ver  Env         Status        Verified At
+  checkout-ui  2.0.0         payment-service   v2.1.0        production  COMPATIBLE    2025-05-01 14:30
+  mobile-app   1.5.0         payment-service   v2.1.0        production  INCOMPATIBLE  2025-05-01 14:30
+```
+
+### BDCT JSON Output
+
+All BDCT commands support `--json` for CI parsing:
+
+```bash
+specshield bdct can-i-deploy --org acme-store --service payment-service --version v2.1.0 --json
+```
+
+```json
+{
+  "deployable": false,
+  "service": "payment-service",
+  "version": "v2.1.0",
+  "environment": "production",
+  "reason": "payment-service v2.1.0 is INCOMPATIBLE with: checkout-ui@2.0.0 (INCOMPATIBLE)",
+  "verifications": [
+    {
+      "consumerName": "checkout-ui",
+      "consumerVersion": "2.0.0",
+      "status": "INCOMPATIBLE",
+      "compatibleCount": 1,
+      "incompatibleCount": 1
+    }
+  ]
+}
+```
+
+### Full BDCT Workflow
+
+```bash
+# 1. Provider publishes spec on every release
+specshield bdct publish-provider \
+  --org acme-store --provider payment-service \
+  --version v2.1.0 --spec ./api/openapi.yaml
+
+# 2. Each consumer publishes their contract once (update on contract change)
+specshield bdct publish-consumer \
+  --org acme-store --consumer checkout-ui \
+  --provider payment-service --version 2.0.0 \
+  --contract ./contracts/checkout-ui.yaml
+
+# 3. Gate the provider deployment
+specshield bdct can-i-deploy \
+  --org acme-store --service payment-service \
+  --version v2.1.0 --env production
+```
+
+---
+
 ## CI/CD — GitHub Actions
 
 ### On Pull Request — Catch breaking changes before merge
@@ -432,7 +780,7 @@ jobs:
         run: specshield compare /tmp/base.yaml api/openapi.yaml --fail-on-breaking
 ```
 
-### On Push — Publish consumer contract
+### On Push — Publish consumer contract (CDCT)
 
 ```yaml
 name: Publish Contract
@@ -462,7 +810,7 @@ jobs:
             --tag ${{ github.ref_name }}
 ```
 
-### On Push — Verify provider + gate deployment
+### On Push — Verify provider + gate deployment (CDCT)
 
 ```yaml
 name: Contract Verification
@@ -499,6 +847,79 @@ jobs:
             --env staging
 ```
 
+### On Push — Publish provider spec (BDCT)
+
+```yaml
+name: BDCT Publish Provider Spec
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'api/openapi.yaml'
+
+jobs:
+  publish-bdct:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g specshield
+      - name: Publish provider spec
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield bdct publish-provider \
+            --org ${{ vars.SPECSHIELD_ORG }} \
+            --provider payment-service \
+            --version ${{ github.sha }} \
+            --spec ./api/openapi.yaml \
+            --env production
+      - name: Gate deployment
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield bdct can-i-deploy \
+            --org ${{ vars.SPECSHIELD_ORG }} \
+            --service payment-service \
+            --version ${{ github.sha }} \
+            --env production
+```
+
+### On Contract Change — Publish consumer contract (BDCT)
+
+```yaml
+name: BDCT Publish Consumer Contract
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'contracts/bdct/**'
+
+jobs:
+  publish-consumer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g specshield
+      - name: Publish consumer contract
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield bdct publish-consumer \
+            --org ${{ vars.SPECSHIELD_ORG }} \
+            --consumer checkout-ui \
+            --provider payment-service \
+            --version ${{ github.ref_name }} \
+            --contract ./contracts/bdct/checkout-ui-payment.yaml
+```
+
 ---
 
 ## Config File
@@ -517,6 +938,11 @@ remote:
   url: "https://specshield.io/compare"
   timeout: 10000
   # apiKey: ""  ← use env var instead
+
+github:
+  specPath: api/openapi.yaml
+  failOnBreaking: true
+  commentOnPr: true
 ```
 
 CLI flags always override config file values.
@@ -542,14 +968,31 @@ specshield compare <base> <target> [options]
 | `--config <path>` | Path to `.specshield.yml` |
 | `--timeout <ms>` | Request timeout for remote mode |
 
+```bash
+specshield bdct <subcommand> [options]
+```
+
+| Subcommand | Description |
+|---|---|
+| `publish-provider` | Publish a provider OpenAPI spec |
+| `publish-consumer` | Publish a consumer contract (OpenAPI subset or Pact JSON) |
+| `verify` | Manually trigger verification for a consumer/provider pair |
+| `can-i-deploy` | Check if a service version is safe to deploy |
+| `matrix` | View compatibility matrix across all pairs |
+| `list-providers` | List published provider specs |
+| `list-consumers` | List published consumer contracts |
+| `list-verifications` | List verification history |
+
+All `bdct` subcommands support `--json` for machine-readable output.
+
 ---
 
 ## Exit Codes
 
 | Code | Meaning |
 |---|---|
-| `0` | Clean — no breaking changes |
-| `1` | Breaking changes found with `--fail-on-breaking` |
+| `0` | Clean — no breaking changes / deployable |
+| `1` | Breaking changes found / not deployable |
 | `2` | Config error, missing token, or runtime error |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "1.0.13",
+  "version": "2.0.0",
   "description": "CLI to compare OpenAPI/Swagger specs and detect breaking changes for CI/CD pipelines and local developer workflows.",
   "main": "src/cli.js",
   "bin": {

package/src/api/bdctClient.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const axios = require('axios');
+const { version } = require('../../package.json');
+
+const DEFAULT_SERVER = 'https://specshield.io';
+const TIMEOUT = 15000;
+
+function buildClient(server, apiToken) {
+  const baseURL = (server || DEFAULT_SERVER).replace(/\/$/, '');
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-SpecShield-Client': 'cli',
+    'X-SpecShield-Version': version,
+  };
+  if (apiToken) headers['X-Api-Key'] = apiToken;
+  return axios.create({ baseURL, timeout: TIMEOUT, headers });
+}
+
+function apiError(err) {
+  if (err.response) {
+    const data = err.response.data;
+    const msg = (data && (data.message || data.error || data.title))
+      || `HTTP ${err.response.status}`;
+    return new Error(`API error (${err.response.status}): ${msg}`);
+  }
+  if (err.request) return new Error(`No response from server: ${err.message}`);
+  return new Error(`Request failed: ${err.message}`);
+}
+
+async function publishProviderSpec(server, apiToken, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post('/api/bdct/provider-specs', payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function publishConsumerContract(server, apiToken, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post('/api/bdct/consumer-contracts', payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function verify(server, apiToken, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post('/api/bdct/verify', payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function listVerifications(server, apiToken, { org, consumer, provider, env, page = 0, size = 20 } = {}) {
+  try {
+    const params = { page, size };
+    if (org)      params.orgKey = org;
+    if (consumer) params.consumer = consumer;
+    if (provider) params.provider = provider;
+    if (env)      params.env = env;
+    const res = await buildClient(server, apiToken).get('/api/bdct/verifications', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function canIDeploy(server, apiToken, { org, service, version: ver, env } = {}) {
+  try {
+    const params = { service, version: ver };
+    if (org) params.orgKey = org;
+    if (env) params.env = env;
+    const res = await buildClient(server, apiToken).get('/api/bdct/can-i-deploy', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function getMatrix(server, apiToken, { org, env } = {}) {
+  try {
+    const params = {};
+    if (org) params.orgKey = org;
+    if (env) params.env = env;
+    const res = await buildClient(server, apiToken).get('/api/bdct/matrix', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function listProviderSpecs(server, apiToken, { org, provider, env, page = 0, size = 20 } = {}) {
+  try {
+    const params = { page, size };
+    if (org)      params.orgKey = org;
+    if (provider) params.provider = provider;
+    if (env)      params.env = env;
+    const res = await buildClient(server, apiToken).get('/api/bdct/provider-specs', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function listConsumerContracts(server, apiToken, { org, consumer, provider, page = 0, size = 20 } = {}) {
+  try {
+    const params = { page, size };
+    if (org)      params.orgKey = org;
+    if (consumer) params.consumer = consumer;
+    if (provider) params.provider = provider;
+    const res = await buildClient(server, apiToken).get('/api/bdct/consumer-contracts', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+module.exports = {
+  publishProviderSpec,
+  publishConsumerContract,
+  verify,
+  listVerifications,
+  canIDeploy,
+  getMatrix,
+  listProviderSpecs,
+  listConsumerContracts,
+};

package/src/cli.js

@@ -6,6 +6,7 @@ const compareCommand = require('./commands/compare');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
 const contractsCommand = require('./commands/contracts');
+const bdctCommand = require('./commands/bdct');
 
 const program = new Command();
 
@@ -18,6 +19,7 @@ program.addCommand(compareCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(contractsCommand);
+program.addCommand(bdctCommand);
 
 program.parseAsync(process.argv).catch((err) => {
   const logger = require('./utils/logger');

package/src/commands/bdct.js

@@ -0,0 +1,648 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const path = require('path');
+const fsExtra = require('fs-extra');
+const logger = require('../utils/logger');
+const { getStoredApiKey } = require('../config/localConfig');
+const {
+  publishProviderSpec,
+  publishConsumerContract,
+  verify,
+  listVerifications,
+  canIDeploy,
+  getMatrix,
+  listProviderSpecs,
+  listConsumerContracts,
+} = require('../api/bdctClient');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+async function resolveApiToken(opts) {
+  return opts.apiToken || process.env.SPECSHIELD_API_KEY || (await getStoredApiKey()) || null;
+}
+
+function requireToken(token) {
+  if (!token) {
+    logger.error('No API token found. Pass --api-token, set SPECSHIELD_API_KEY, or run: specshield login --api-key <KEY>');
+    process.exit(2);
+  }
+}
+
+function fmtDate(iso) {
+  if (!iso) return chalk.gray('—');
+  try {
+    return new Date(iso).toLocaleString('en-IN', { timeZone: 'Asia/Kolkata', hour12: false })
+      .replace(',', '');
+  } catch { return iso; }
+}
+
+function compatBadge(status) {
+  if (!status) return chalk.gray('UNKNOWN');
+  const s = String(status).toUpperCase();
+  if (s === 'COMPATIBLE')   return chalk.green(s);
+  if (s === 'INCOMPATIBLE') return chalk.red(s);
+  return chalk.gray(s);
+}
+
+function hr() {
+  return chalk.gray('  ─────────────────────────────────────────────────────');
+}
+
+/** Strip ANSI escape codes for length measurement */
+function stripAnsi(str) {
+  return str.replace(/\[[0-9;]*m/g, '');
+}
+
+/** Simple padded column table */
+function printTable(headers, rows) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map(r => stripAnsi(String(r[i] ?? '')).length))
+  );
+  const headerLine = headers.map((h, i) => chalk.bold(h.padEnd(widths[i]))).join('  ');
+  process.stdout.write('\n  ' + headerLine + '\n');
+  process.stdout.write('  ' + widths.map(w => '─'.repeat(w)).join('  ') + '\n');
+  for (const row of rows) {
+    const line = row.map((cell, i) => {
+      const raw = String(cell ?? '');
+      const pad = widths[i] - stripAnsi(raw).length;
+      return raw + ' '.repeat(Math.max(0, pad));
+    }).join('  ');
+    process.stdout.write('  ' + line + '\n');
+  }
+  process.stdout.write('\n');
+}
+
+// ─── publish-provider ────────────────────────────────────────────────────────
+
+const publishProviderCommand = new Command('publish-provider')
+  .description('Publish a provider OpenAPI spec to the BDCT registry')
+  .requiredOption('--spec <path>', 'Path to provider spec file (YAML or JSON)')
+  .requiredOption('--provider <name>', 'Provider service name')
+  .requiredOption('--version <ver>', 'Provider version tag')
+  .option('--env <environment>', 'Environment label (e.g. staging, production)')
+  .option('--org <key>', 'Organization key')
+  .option('--branch <branch>', 'Git branch name')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token (overrides env / stored config)')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const filePath = path.resolve(opts.spec);
+    if (!(await fsExtra.pathExists(filePath))) {
+      logger.error(`Spec file not found: ${filePath}`);
+      process.exit(2);
+    }
+
+    let specContent;
+    try {
+      specContent = await fsExtra.readFile(filePath, 'utf8');
+    } catch (err) {
+      logger.error(`Failed to read spec file: ${err.message}`);
+      process.exit(2);
+    }
+
+    const spinner = opts.json ? null : ora('Publishing provider spec...').start();
+
+    try {
+      const result = await publishProviderSpec(opts.server, token, {
+        provider:    opts.provider,
+        version:     opts.version,
+        specContent,
+        env:         opts.env    || null,
+        orgKey:      opts.org    || null,
+        branch:      opts.branch || null,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.green.bold('  ✔  Provider Spec Published') + '\n');
+      process.stdout.write(hr() + '\n');
+      if (result.id)       process.stdout.write(`  ID          : ${chalk.cyan(result.id)}\n`);
+      process.stdout.write(`  Provider    : ${chalk.white(opts.provider)}\n`);
+      process.stdout.write(`  Version     : ${chalk.cyan(opts.version)}\n`);
+      if (opts.env)        process.stdout.write(`  Environment : ${opts.env}\n`);
+      if (result.publishedAt) process.stdout.write(`  Published At: ${fmtDate(result.publishedAt)}\n`);
+      process.stdout.write('\n');
+    } catch (err) {
+      if (spinner) spinner.fail('Publish failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── publish-consumer ────────────────────────────────────────────────────────
+
+const publishConsumerCommand = new Command('publish-consumer')
+  .description('Publish a consumer contract to the BDCT registry')
+  .requiredOption('--contract <path>', 'Path to consumer contract file (OpenAPI YAML/JSON or Pact JSON)')
+  .requiredOption('--consumer <name>', 'Consumer service name')
+  .requiredOption('--provider <name>', 'Provider service name')
+  .requiredOption('--version <ver>', 'Consumer version tag')
+  .option('--org <key>', 'Organization key')
+  .option('--format <fmt>', 'Contract format: OPENAPI | PACT', 'OPENAPI')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token (overrides env / stored config)')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const filePath = path.resolve(opts.contract);
+    if (!(await fsExtra.pathExists(filePath))) {
+      logger.error(`Contract file not found: ${filePath}`);
+      process.exit(2);
+    }
+
+    let contractContent;
+    try {
+      contractContent = await fsExtra.readFile(filePath, 'utf8');
+    } catch (err) {
+      logger.error(`Failed to read contract file: ${err.message}`);
+      process.exit(2);
+    }
+
+    const spinner = opts.json ? null : ora('Publishing consumer contract...').start();
+
+    try {
+      const result = await publishConsumerContract(opts.server, token, {
+        consumer:        opts.consumer,
+        provider:        opts.provider,
+        version:         opts.version,
+        contractContent,
+        orgKey:          opts.org    || null,
+        format:          opts.format || 'OPENAPI',
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.green.bold('  ✔  Consumer Contract Published') + '\n');
+      process.stdout.write(hr() + '\n');
+      if (result.id)       process.stdout.write(`  ID          : ${chalk.cyan(result.id)}\n`);
+      process.stdout.write(`  Consumer    : ${chalk.white(opts.consumer)}\n`);
+      process.stdout.write(`  Provider    : ${chalk.white(opts.provider)}\n`);
+      process.stdout.write(`  Version     : ${chalk.cyan(opts.version)}\n`);
+      process.stdout.write(`  Format      : ${opts.format || 'OPENAPI'}\n`);
+      if (result.publishedAt) process.stdout.write(`  Published At: ${fmtDate(result.publishedAt)}\n`);
+      process.stdout.write('\n');
+      process.stdout.write(chalk.gray(`  ➜  Run: specshield bdct verify --consumer ${opts.consumer} --provider ${opts.provider}\n`));
+      process.stdout.write('\n');
+    } catch (err) {
+      if (spinner) spinner.fail('Publish failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── verify ──────────────────────────────────────────────────────────────────
+
+const verifyCommand = new Command('verify')
+  .description('Verify consumer-provider contract compatibility')
+  .requiredOption('--consumer <name>', 'Consumer service name')
+  .requiredOption('--provider <name>', 'Provider service name')
+  .option('--consumer-version <ver>', 'Consumer version to verify')
+  .option('--provider-version <ver>', 'Provider version to verify against')
+  .option('--env <environment>', 'Environment label')
+  .option('--org <key>', 'Organization key')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const spinner = opts.json ? null : ora(`Verifying ${opts.consumer} → ${opts.provider}...`).start();
+
+    try {
+      const result = await verify(opts.server, token, {
+        consumer:        opts.consumer,
+        provider:        opts.provider,
+        consumerVersion: opts.consumerVersion || null,
+        providerVersion: opts.providerVersion || null,
+        env:             opts.env             || null,
+        orgKey:          opts.org             || null,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+
+      const status  = String(result.status || result.result || '').toUpperCase();
+      const success = status === 'COMPATIBLE';
+
+      process.stdout.write('\n');
+      if (success) {
+        process.stdout.write(chalk.green.bold('  ✔  COMPATIBLE') + '\n');
+      } else {
+        process.stdout.write(chalk.red.bold('  ✖  INCOMPATIBLE') + '\n');
+      }
+      process.stdout.write(hr() + '\n');
+      if (result.id) process.stdout.write(`  Verification ID : ${chalk.cyan(result.id)}\n`);
+      process.stdout.write(`  Consumer        : ${opts.consumer}${opts.consumerVersion ? '@' + opts.consumerVersion : ''}\n`);
+      process.stdout.write(`  Provider        : ${opts.provider}${opts.providerVersion ? '@' + opts.providerVersion : ''}\n`);
+      if (opts.env) process.stdout.write(`  Environment     : ${opts.env}\n`);
+      process.stdout.write(`  Result          : ${compatBadge(status)}\n`);
+      if (result.verifiedAt || result.completedAt) {
+        process.stdout.write(`  Verified At     : ${fmtDate(result.verifiedAt || result.completedAt)}\n`);
+      }
+
+      const issues = result.issues || result.mismatches || [];
+      if (issues.length > 0) {
+        process.stdout.write('\n');
+        process.stdout.write(chalk.red.bold('  Issues') + '\n');
+        process.stdout.write(hr() + '\n');
+        for (const issue of issues) {
+          process.stdout.write(`  ${chalk.red('●')} ${chalk.bold(issue.type || issue.mismatchType || 'MISMATCH')} at ${chalk.gray(issue.path || '$')}\n`);
+          if (issue.message) process.stdout.write(`    ${chalk.gray(issue.message)}\n`);
+        }
+        process.stdout.write('\n');
+      }
+
+      process.stdout.write('\n');
+      process.exit(success ? 0 : 1);
+    } catch (err) {
+      if (spinner) spinner.fail('Verification failed');
+      logger.error(err.message);
+      process.exit(2);
+    }
+  });
+
+// ─── can-i-deploy ─────────────────────────────────────────────────────────────
+
+const canIDeployCommand = new Command('can-i-deploy')
+  .description('Check if a service version is safe to deploy')
+  .requiredOption('--service <name>', 'Service name (consumer or provider)')
+  .requiredOption('--version <ver>', 'Service version to check')
+  .option('--env <environment>', 'Target environment (e.g. qa, staging, production)')
+  .option('--org <key>', 'Organization key')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const spinner = opts.json ? null : ora(`Checking deployment safety for ${opts.service}@${opts.version}...`).start();
+
+    try {
+      const result = await canIDeploy(opts.server, token, {
+        service: opts.service,
+        version: opts.version,
+        env:     opts.env || null,
+        org:     opts.org || null,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+
+      const deployable = result.deployable ?? result.allowed ?? false;
+      const envLabel   = opts.env ? ` in ${opts.env}` : '';
+
+      process.stdout.write('\n');
+      if (deployable) {
+        process.stdout.write(chalk.green.bold('  ✔  PASS') + chalk.white(`: ${opts.service} v${opts.version} is deployable${envLabel}\n`));
+      } else {
+        process.stdout.write(chalk.red.bold('  ✖  FAIL') + chalk.white(`: ${opts.service} v${opts.version} is NOT deployable${envLabel}\n`));
+      }
+      process.stdout.write(hr() + '\n');
+
+      const consumers = result.consumers || result.verifications || [];
+      if (consumers.length > 0) {
+        process.stdout.write('\n');
+        process.stdout.write(chalk.bold('  Consumer Verifications') + '\n');
+        printTable(
+          ['Consumer', 'Version', 'Status', 'Verified At'],
+          consumers.map(c => [
+            c.consumer || c.consumerName || '—',
+            c.consumerVersion || c.version || '—',
+            compatBadge(c.status || c.result),
+            fmtDate(c.verifiedAt || c.completedAt),
+          ])
+        );
+      }
+
+      if (!deployable) {
+        process.stdout.write(chalk.gray(`  ➜  Run: specshield bdct verify --consumer <NAME> --provider ${opts.service}\n`));
+        process.stdout.write(chalk.gray(`  ➜  to identify and resolve incompatibilities\n`));
+        process.stdout.write('\n');
+        process.exit(1);
+      } else {
+        process.stdout.write('\n');
+        process.exit(0);
+      }
+    } catch (err) {
+      if (spinner) spinner.fail('Check failed');
+      logger.error(err.message);
+      process.exit(2);
+    }
+  });
+
+// ─── list ─────────────────────────────────────────────────────────────────────
+
+const listCommand = new Command('list')
+  .description('List BDCT verification history')
+  .option('--org <key>', 'Filter by organization key')
+  .option('--consumer <name>', 'Filter by consumer service name')
+  .option('--provider <name>', 'Filter by provider service name')
+  .option('--env <environment>', 'Filter by environment')
+  .option('--page <n>', 'Page number (0-based)', '0')
+  .option('--size <n>', 'Page size', '20')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const spinner = opts.json ? null : ora('Fetching verification history...').start();
+
+    try {
+      const page = await listVerifications(opts.server, token, {
+        org:      opts.org,
+        consumer: opts.consumer,
+        provider: opts.provider,
+        env:      opts.env,
+        page:     parseInt(opts.page, 10) || 0,
+        size:     parseInt(opts.size, 10)  || 20,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(page, null, 2) + '\n');
+        return;
+      }
+
+      const items = page.content || (Array.isArray(page) ? page : []);
+      const total = page.totalElements ?? items.length;
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold('  BDCT Verification History') + '\n');
+      process.stdout.write(hr() + '\n');
+      process.stdout.write(`  Showing ${items.length} of ${total} verifications\n`);
+
+      if (items.length === 0) {
+        process.stdout.write(chalk.gray('\n  No verifications found matching filters.\n\n'));
+        return;
+      }
+
+      printTable(
+        ['ID', 'Consumer', 'Provider', 'Cons Ver', 'Prov Ver', 'Status', 'Environment', 'Verified At'],
+        items.map(v => [
+          chalk.cyan(String(v.id ?? v.verificationId ?? '—')),
+          v.consumer || v.consumerName || '—',
+          v.provider || v.providerName || '—',
+          v.consumerVersion || '—',
+          v.providerVersion || '—',
+          compatBadge(v.status || v.result),
+          v.env || v.environment || '—',
+          fmtDate(v.verifiedAt || v.completedAt),
+        ])
+      );
+
+      if (page.totalPages > 1) {
+        const cur = (page.number ?? 0) + 1;
+        process.stdout.write(chalk.gray(`  Page ${cur} of ${page.totalPages}  ·  Use --page and --size to navigate\n\n`));
+      }
+    } catch (err) {
+      if (spinner) spinner.fail('List failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── matrix ──────────────────────────────────────────────────────────────────
+
+const matrixCommand = new Command('matrix')
+  .description('Show ASCII compatibility matrix of consumers vs providers')
+  .option('--org <key>', 'Organization key')
+  .option('--env <environment>', 'Environment label')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const spinner = opts.json ? null : ora('Fetching compatibility matrix...').start();
+
+    try {
+      const matrix = await getMatrix(opts.server, token, {
+        org: opts.org,
+        env: opts.env,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(matrix, null, 2) + '\n');
+        return;
+      }
+
+      // Expected matrix shape: { consumers: string[], providers: string[], cells: { [consumer]: { [provider]: string } } }
+      const consumers = matrix.consumers || [];
+      const providers = matrix.providers || [];
+      const cells     = matrix.cells     || {};
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold('  BDCT Compatibility Matrix') + '\n');
+      if (opts.env) process.stdout.write(chalk.gray(`  Environment: ${opts.env}\n`));
+      process.stdout.write(hr() + '\n');
+
+      if (consumers.length === 0 || providers.length === 0) {
+        process.stdout.write(chalk.gray('\n  No data available. Publish provider specs and consumer contracts first.\n\n'));
+        return;
+      }
+
+      // Build table: first column = consumer label, remaining = providers
+      const headers = ['Consumer \\ Provider', ...providers];
+      const rows = consumers.map(consumer => {
+        const providerCells = providers.map(provider => {
+          const status = (cells[consumer] && cells[consumer][provider]) || 'UNKNOWN';
+          return compatBadge(status);
+        });
+        return [chalk.white(consumer), ...providerCells];
+      });
+
+      printTable(headers, rows);
+
+      process.stdout.write(chalk.green('  ■') + chalk.gray(' COMPATIBLE  ') +
+                           chalk.red('■')   + chalk.gray(' INCOMPATIBLE  ') +
+                           chalk.gray('■ UNKNOWN') + '\n\n');
+    } catch (err) {
+      if (spinner) spinner.fail('Fetch failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── list-providers ──────────────────────────────────────────────────────────
+
+const listProvidersCommand = new Command('list-providers')
+  .description('List published provider specs')
+  .option('--org <key>', 'Filter by organization key')
+  .option('--provider <name>', 'Filter by provider service name')
+  .option('--env <environment>', 'Filter by environment')
+  .option('--page <n>', 'Page number (0-based)', '0')
+  .option('--size <n>', 'Page size', '20')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const spinner = opts.json ? null : ora('Fetching provider specs...').start();
+
+    try {
+      const page = await listProviderSpecs(opts.server, token, {
+        org:      opts.org,
+        provider: opts.provider,
+        env:      opts.env,
+        page:     parseInt(opts.page, 10) || 0,
+        size:     parseInt(opts.size, 10)  || 20,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(page, null, 2) + '\n');
+        return;
+      }
+
+      const items = page.content || (Array.isArray(page) ? page : []);
+      const total = page.totalElements ?? items.length;
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold('  Published Provider Specs') + '\n');
+      process.stdout.write(hr() + '\n');
+      process.stdout.write(`  Showing ${items.length} of ${total} specs\n`);
+
+      if (items.length === 0) {
+        process.stdout.write(chalk.gray('\n  No provider specs found matching filters.\n\n'));
+        return;
+      }
+
+      printTable(
+        ['ID', 'Provider', 'Version', 'Environment', 'Branch', 'Published At'],
+        items.map(s => [
+          chalk.cyan(String(s.id ?? '—')),
+          s.provider || s.providerName || '—',
+          chalk.cyan(s.version || '—'),
+          s.env || s.environment || '—',
+          chalk.gray(s.branch || '—'),
+          fmtDate(s.publishedAt),
+        ])
+      );
+
+      if (page.totalPages > 1) {
+        const cur = (page.number ?? 0) + 1;
+        process.stdout.write(chalk.gray(`  Page ${cur} of ${page.totalPages}  ·  Use --page and --size to navigate\n\n`));
+      }
+    } catch (err) {
+      if (spinner) spinner.fail('List failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── list-consumers ──────────────────────────────────────────────────────────
+
+const listConsumersCommand = new Command('list-consumers')
+  .description('List published consumer contracts')
+  .option('--org <key>', 'Filter by organization key')
+  .option('--consumer <name>', 'Filter by consumer service name')
+  .option('--provider <name>', 'Filter by provider service name')
+  .option('--page <n>', 'Page number (0-based)', '0')
+  .option('--size <n>', 'Page size', '20')
+  .option('--json', 'Output raw JSON')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token')
+  .action(async (opts) => {
+    const token = await resolveApiToken(opts);
+    requireToken(token);
+
+    const spinner = opts.json ? null : ora('Fetching consumer contracts...').start();
+
+    try {
+      const page = await listConsumerContracts(opts.server, token, {
+        org:      opts.org,
+        consumer: opts.consumer,
+        provider: opts.provider,
+        page:     parseInt(opts.page, 10) || 0,
+        size:     parseInt(opts.size, 10)  || 20,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(page, null, 2) + '\n');
+        return;
+      }
+
+      const items = page.content || (Array.isArray(page) ? page : []);
+      const total = page.totalElements ?? items.length;
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold('  Published Consumer Contracts') + '\n');
+      process.stdout.write(hr() + '\n');
+      process.stdout.write(`  Showing ${items.length} of ${total} contracts\n`);
+
+      if (items.length === 0) {
+        process.stdout.write(chalk.gray('\n  No consumer contracts found matching filters.\n\n'));
+        return;
+      }
+
+      printTable(
+        ['ID', 'Consumer', 'Provider', 'Version', 'Format', 'Published At'],
+        items.map(c => [
+          chalk.cyan(String(c.id ?? '—')),
+          c.consumer || c.consumerName || '—',
+          c.provider || c.providerName || '—',
+          chalk.cyan(c.version || '—'),
+          c.format || '—',
+          fmtDate(c.publishedAt),
+        ])
+      );
+
+      if (page.totalPages > 1) {
+        const cur = (page.number ?? 0) + 1;
+        process.stdout.write(chalk.gray(`  Page ${cur} of ${page.totalPages}  ·  Use --page and --size to navigate\n\n`));
+      }
+    } catch (err) {
+      if (spinner) spinner.fail('List failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── Parent bdct command ──────────────────────────────────────────────────────
+
+const bdct = new Command('bdct')
+  .description('Bi-Directional Contract Testing (BDCT) — publish specs, verify compatibility, check deployability');
+
+bdct.addCommand(publishProviderCommand);
+bdct.addCommand(publishConsumerCommand);
+bdct.addCommand(verifyCommand);
+bdct.addCommand(canIDeployCommand);
+bdct.addCommand(listCommand);
+bdct.addCommand(matrixCommand);
+bdct.addCommand(listProvidersCommand);
+bdct.addCommand(listConsumersCommand);
+
+module.exports = bdct;