specshield 1.0.6 → 1.0.8

package/README.md

@@ -5,7 +5,89 @@
 [![license](https://img.shields.io/badge/license-MIT-blue)](#license)
 [![node](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
 
-Compare OpenAPI and Swagger specs, detect breaking changes, and fail CI before incompatible API changes reach production.
+## 🚀 Prevent Breaking API Changes Before They Reach Production
+
+**SpecShield is a Pact alternative for OpenAPI** that helps developers  
+**detect breaking API changes in CI/CD** and act as a powerful  
+**OpenAPI diff tool for modern backend teams.**
+
+---
+
+## 👀 See it in action
+
+```bash
+$ specshield compare base.yaml target.yaml --fail-on-breaking
+
+✖ BREAKING CHANGES DETECTED
+
+  1. DELETE /users endpoint removed
+  2. POST /payments request field "amount" changed from optional to required
+  3. GET /orders/{id} response field "status" type changed: string -> object
+
+Summary
+- Breaking changes : 3
+- Modifications    : 1
+- Additions        : 2
+- Warnings         : 0
+
+CI Result: FAILED
+Exit Code: 1
+```
+
+These are the kinds of changes that break clients in production.  
+SpecShield catches them early so your CI can block unsafe deployments.
+
+### Safe change example
+
+```bash
+$ specshield compare base.yaml target.yaml --fail-on-breaking
+
+✔ NO BREAKING CHANGES FOUND
+
+Summary
+- Breaking changes : 0
+- Modifications    : 1
+- Additions        : 3
+- Warnings         : 1
+
+CI Result: PASSED
+Exit Code: 0
+```
+
+---
+
+## ⚡ 30-second quick start
+
+```bash
+npm install -g specshield
+specshield compare base.yaml target.yaml --fail-on-breaking
+```
+
+👉 No account required for local compare
+
+---
+
+## 💡 Useful for
+
+- Preventing accidental API breakage in pull requests
+- Failing CI when breaking changes are introduced
+- Tracking API drift across versions
+- Enforcing contracts between consumer and provider services
+
+---
+
+## 🌐 Upgrade to Remote
+
+Local compare is free and unlimited.
+
+Remote mode unlocks:
+
+- 📊 API change history
+- 👥 Team collaboration
+- 🚦 Deployment gating (`can-i-deploy`)
+- 🔗 Contract testing across services
+
+👉 https://specshield.io
 
 ---
 
@@ -15,8 +97,18 @@ Compare OpenAPI and Swagger specs, detect breaking changes, and fail CI before i
 - [Installation](#installation)
 - [Local Compare](#local-compare)
 - [Authentication](#authentication)
-- [Generate an API Token](#generate-an-api-token)
+  - [Generate an API Token](#generate-an-api-token)
 - [Remote Compare](#remote-compare)
+- [Contracts — Consumer-Driven Testing](#contracts--consumer-driven-testing)
+  - [Contract File Format](#contract-file-format)
+  - [Publish a Contract](#publish-a-contract)
+  - [List Contracts](#list-contracts)
+  - [Get Latest Contract](#get-latest-contract)
+  - [Verify a Contract](#verify-a-contract)
+  - [Verification History](#verification-history)
+  - [Can I Deploy?](#can-i-deploy)
+  - [Full Publish → Verify → Deploy Workflow](#full-publish--verify--deploy-workflow)
+  - [Contracts in CI/CD](#contracts-in-cicd)
 - [Config File](#config-file)
 - [All Options](#all-options)
 - [Exit Codes](#exit-codes)
@@ -27,12 +119,11 @@ Compare OpenAPI and Swagger specs, detect breaking changes, and fail CI before i
 
 ## What is SpecShield CLI?
 
-SpecShield CLI is a command-line tool for comparing two OpenAPI/Swagger specifications and detecting what changed between them. It classifies changes into:
+SpecShield CLI is a developer-first **OpenAPI diff tool** and  
+**contract testing solution** that helps prevent breaking API changes.
 
-- **Breaking changes** — removed endpoints, changed required fields, incompatible type changes
-- **Modifications** — changed behavior that may or may not break clients
-- **Additions** — new endpoints or fields
-- **Warnings** — low-severity notices
+It works as a lightweight **Pact alternative for OpenAPI**, designed for  
+modern microservices and CI/CD pipelines.
 
 It works in two modes:
 
@@ -121,7 +212,7 @@ This validates the token against the SpecShield API and saves it to `~/.specshie
 
 **Example output:**
 
-```
+```text
 ✔ Logged in successfully.
 
   Customer:  Jane Smith
@@ -188,12 +279,465 @@ specshield compare base.yaml target.yaml --remote --json --output result.json
 
 The CLI reads your API token (from flag, env var, or stored config) and sends it as an `X-Api-Key` header with each request. If no token is found, the command exits with an error:
 
-```
+```text
 Error: No API key found. Run: specshield login --api-key <KEY>
 ```
 
 ---
 
+## Contracts — Consumer-Driven Testing
+
+SpecShield Contracts lets consumer teams publish API expectations (contracts) to a central registry. Provider teams then verify their service satisfies those contracts before deploying.
+
+**Why contract testing?**
+- Catch provider-side regressions before they reach consumers
+- Enforce an agreed-upon API shape across services
+- Gate deployments on verified contracts with `can-i-deploy`
+
+All contract commands require an API token. See [Authentication](#authentication).
+
+### Contract File Format
+
+Create a `.json` file describing the expected API interactions:
+
+```json
+{
+  "consumer": {
+    "name": "checkout-ui",
+    "version": "1.2.0"
+  },
+  "provider": {
+    "name": "payment-service"
+  },
+  "contractName": "create-payment",
+  "contractType": "HTTP",
+  "interactions": [
+    {
+      "description": "create payment",
+      "request": {
+        "method": "POST",
+        "path": "/payments",
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "orderId": "ORD-123",
+          "amount": 100,
+          "currency": "INR"
+        }
+      },
+      "expectedResponse": {
+        "status": 201,
+        "headers": {
+          "Content-Type": "application/json"
+        },
+        "body": {
+          "paymentId": "PAY-123",
+          "status": "CREATED"
+        }
+      }
+    }
+  ],
+  "metadata": {
+    "generatedBy": "specshield-cli",
+    "contractFormatVersion": "1.0"
+  }
+}
+```
+
+The `consumer.name`, `provider.name`, and `contractName` fields are used to identify the contract in the registry. CLI flags (`--consumer`, `--provider`, `--contract-name`) override file values if provided.
+
+### Publish a Contract
+
+```bash
+specshield contracts publish \\
+  --file ./contracts/create-payment.json \\
+  --org acme
+```
+
+With all flags explicitly set (flags override file values):
+
+```bash
+specshield contracts publish \\
+  --file ./contracts/create-payment.json \\
+  --org acme \\
+  --consumer checkout-ui \\
+  --provider payment-service \\
+  --contract-name create-payment \\
+  --consumer-version 1.2.0 \\
+  --tag main
+```
+
+**Example output:**
+
+```text
+  ✔  Contract Published Successfully
+  ─────────────────────────────────────────────────────
+  Contract ID     : 42
+  Contract Name   : create-payment
+  Consumer        : checkout-ui
+  Provider        : payment-service
+  Version         : 3
+  Status          : PUBLISHED
+  Content Hash    : a3f9c1d2e7b8...
+  Published At    : 06/04/2026 14:30:00
+
+  ➜  Run: specshield contracts verify --contract-id 42 --base-url http://localhost:8080
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--file <path>` | Path to contract JSON file (required) |
+| `--org <key>` | Organization key |
+| `--consumer <key>` | Consumer service key (overrides file) |
+| `--provider <key>` | Provider service key (overrides file) |
+| `--consumer-version <ver>` | Consumer version tag |
+| `--contract-name <name>` | Contract name (overrides file) |
+| `--tag <tag>` | Git branch or release tag |
+| `--server <url>` | SpecShield server URL (default: `https://specshield.io`) |
+| `--api-token <token>` | API token |
+
+### List Contracts
+
+```bash
+specshield contracts list
+```
+
+Filter by provider:
+
+```bash
+specshield contracts list --provider payment-service
+```
+
+Filter by consumer, org, status:
+
+```bash
+specshield contracts list \\
+  --consumer checkout-ui \\
+  --provider payment-service \\
+  --status PUBLISHED
+```
+
+Output raw JSON:
+
+```bash
+specshield contracts list --json
+```
+
+**Example output:**
+
+```text
+  SpecShield Contract Registry
+  ─────────────────────────────────────────────────────
+  Showing 2 of 2 contracts
+
+  ID  Contract Name    Consumer      Provider         Ver  Status     Last Verify  Published
+  ──  ───────────────  ────────────  ───────────────  ───  ─────────  ───────────  ─────────────────────
+  42  create-payment   checkout-ui   payment-service  3    PUBLISHED  SUCCESS      06/04/2026 14:30:00
+  41  get-order-status order-ui      order-service    1    PUBLISHED  FAILED       05/04/2026 09:15:00
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--consumer <key>` | Filter by consumer |
+| `--provider <key>` | Filter by provider |
+| `--org <key>` | Filter by organization |
+| `--status <status>` | Filter by status (`PUBLISHED` / `DEPRECATED`) |
+| `--contract-name <name>` | Filter by contract name |
+| `--page <n>` | Page number (0-based, default: `0`) |
+| `--size <n>` | Page size (default: `20`) |
+| `--json` | Output raw JSON |
+
+### Get Latest Contract
+
+```bash
+specshield contracts latest \\
+  --consumer checkout-ui \\
+  --provider payment-service \\
+  --contract-name create-payment
+```
+
+Print the full contract content (interactions, body, etc.):
+
+```bash
+specshield contracts latest \\
+  --consumer checkout-ui \\
+  --provider payment-service \\
+  --json
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--consumer <key>` | Consumer service key |
+| `--provider <key>` | Provider service key |
+| `--org <key>` | Organization key |
+| `--contract-name <name>` | Contract name |
+| `--json` | Print full contract JSON |
+
+### Verify a Contract
+
+Run the contract against a live provider. SpecShield replays each interaction against the `--base-url` and compares the response to the expected values.
+
+```bash
+specshield contracts verify \\
+  --contract-id 42 \\
+  --base-url http://localhost:8080
+```
+
+With version and environment tags:
+
+```bash
+specshield contracts verify \\
+  --contract-id 42 \\
+  --base-url https://payment-service.staging.internal \\
+  --provider-version v2.1.0 \\
+  --env staging
+```
+
+Output raw JSON (for CI parsing):
+
+```bash
+specshield contracts verify \\
+  --contract-id 42 \\
+  --base-url http://localhost:8080 \\
+  --json
+```
+
+**Example output (pass):**
+
+```text
+  ✔  Verification PASSED  (1/1 interactions)
+  ─────────────────────────────────────────────────────
+  Verification ID : 101
+  Contract ID     : 42
+  Status          : SUCCESS
+  Started At      : 06/04/2026 14:35:00
+  Completed At    : 06/04/2026 14:35:01
+
+  ➜  Run: specshield contracts can-i-deploy --provider payment-service --version v2.1.0
+```
+
+**Example output (fail):**
+
+```text
+  ✖  Verification FAILED  (0/1 interactions passed, 1 failed)
+  ─────────────────────────────────────────────────────
+  Verification ID : 102
+  Contract ID     : 42
+  Status          : FAILED
+
+  Mismatches
+  ─────────────────────────────────────────────────────
+  ● [create payment] STATUS_CODE_MISMATCH at $.status
+    expected: 201  →  actual: 200
+    Expected status 201 but got 200
+
+  ➜  Run: specshield contracts history --contract-id 42 to inspect previous runs
+```
+
+**Exit codes:** `0` = PASSED, `1` = FAILED, `2` = error
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--contract-id <id>` | Contract ID to verify (required) |
+| `--base-url <url>` | Provider base URL (required, e.g. `http://localhost:8080`) |
+| `--provider-version <ver>` | Provider version tag |
+| `--env <environment>` | Environment label (`staging`, `qa`, `production`) |
+| `--mode <mode>` | `LIVE` or `REPLAY` (default: `LIVE`) |
+| `--json` | Output raw JSON |
+
+### Verification History
+
+```bash
+specshield contracts history --contract-id 42
+```
+
+**Example output:**
+
+```text
+  Verification History — Contract 42
+  ─────────────────────────────────────────────────────
+
+  ID   Status   Environment  Provider Version  Mode  Completed At
+  ───  ───────  ───────────  ────────────────  ────  ─────────────────────
+  102  FAILED   staging      v2.1.0            LIVE  06/04/2026 14:35:01
+  101  SUCCESS  staging      v2.0.0            LIVE  05/04/2026 10:00:00
+  98   SUCCESS  qa           v1.9.0            LIVE  01/04/2026 08:30:00
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--contract-id <id>` | Contract ID (required) |
+| `--json` | Output raw JSON |
+
+### Can I Deploy?
+
+Check whether a provider version has passing verifications for all associated contracts:
+
+```bash
+specshield contracts can-i-deploy \\
+  --provider payment-service \\
+  --version v2.1.0
+```
+
+Scoped to a specific environment:
+
+```bash
+specshield contracts can-i-deploy \\
+  --provider payment-service \\
+  --version v2.1.0 \\
+  --env production
+```
+
+**Example output (allowed):**
+
+```text
+  ✔  PASS: payment-service v2.1.0 is deployable in production
+  ─────────────────────────────────────────────────────
+
+  Contract Decisions
+  ✔ Contract ID 42 — SUCCESS
+    All contracts verified
+```
+
+**Example output (blocked):**
+
+```text
+  ✖  FAIL: payment-service v2.1.0 is NOT deployable in production
+  ─────────────────────────────────────────────────────
+
+  Contract Decisions
+  ✖ Contract ID 43 — FAILED
+    Unverified or failed contracts found
+
+  ➜  Run: specshield contracts verify --contract-id 43 --base-url <URL>
+  ➜  to verify pending contracts before deploying
+```
+
+**Exit codes:** `0` = deployable, `1` = blocked, `2` = error
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--provider <key>` | Provider service key (required) |
+| `--version <ver>` | Provider version to check (required) |
+| `--env <environment>` | Target environment |
+| `--json` | Output raw JSON |
+
+### Full Publish → Verify → Deploy Workflow
+
+```bash
+# 1. Consumer team publishes a contract
+specshield contracts publish \\
+  --file ./contracts/create-payment.json \\
+  --org acme
+
+# 2. Provider team starts their service locally
+./gradlew bootRun &
+
+# 3. Provider team verifies the contract
+specshield contracts verify \\
+  --contract-id 42 \\
+  --base-url http://localhost:8080 \\
+  --provider-version v2.1.0 \\
+  --env staging
+
+# 4. Gate the deployment
+specshield contracts can-i-deploy \\
+  --provider payment-service \\
+  --version v2.1.0 \\
+  --env staging
+```
+
+### Contracts in CI/CD
+
+#### GitHub Actions — Publish on consumer change
+
+```yaml
+name: Publish Contract
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'contracts/**'
+
+jobs:
+  publish-contract:
+    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 contract
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield contracts publish \\
+            --file ./contracts/create-payment.json \\
+            --org acme \\
+            --tag ${{ github.ref_name }}
+```
+
+#### GitHub Actions — Verify + can-i-deploy on provider change
+
+```yaml
+name: Contract Verification
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    services:
+      payment-service:
+        image: myorg/payment-service:${{ github.sha }}
+        ports:
+          - 8080:8080
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g specshield
+
+      - name: Verify contract
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield contracts verify \\
+            --contract-id ${{ vars.PAYMENT_CONTRACT_ID }} \\
+            --base-url http://localhost:8080 \\
+            --provider-version ${{ github.sha }} \\
+            --env staging
+
+      - name: Can I deploy?
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield contracts can-i-deploy \\
+            --provider payment-service \\
+            --version ${{ github.sha }} \\
+            --env staging
+```
+
+---
+
 ## Config File
 
 Create `.specshield.yml` in your project root to set default behavior:
@@ -280,8 +824,8 @@ jobs:
 
       - name: Compare specs
         run: |
-          specshield compare /tmp/base-spec.yaml api/openapi.yaml \
-            --fail-on-breaking \
+          specshield compare /tmp/base-spec.yaml api/openapi.yaml \\
+            --fail-on-breaking \\
             --output spec-diff.json
 
       - name: Upload diff report
@@ -301,9 +845,9 @@ Add your API token as a GitHub Actions secret named `SPECSHIELD_API_KEY`, then:
         env:
           SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
         run: |
-          specshield compare /tmp/base-spec.yaml api/openapi.yaml \
-            --remote \
-            --fail-on-breaking \
+          specshield compare /tmp/base-spec.yaml api/openapi.yaml \\
+            --remote \\
+            --fail-on-breaking \\
             --output spec-diff.json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "CLI to compare OpenAPI/Swagger specs and detect breaking changes for CI/CD pipelines and local developer workflows.",
   "main": "src/cli.js",
   "bin": {
@@ -13,29 +13,37 @@
     "lint": "eslint src tests --ext .js"
   },
   "keywords": [
-    "openapi",
-    "swagger",
-    "openapi-diff",
-    "swagger-diff",
-    "api-diff",
-    "api-breaking-changes",
-    "breaking-change-detection",
-    "contract-testing",
-    "api-contract",
-    "api-versioning",
-    "api-governance",
-    "ci-cd",
-    "devops",
-    "github-actions",
-    "automation",
-    "cli",
-    "developer-tools",
-    "yaml",
-    "json",
-    "schema-diff",
-    "rest-api",
-    "openapi-cli"
-  ],
+  "openapi",
+  "swagger",
+  "api-diff",
+  "openapi-diff",
+  "swagger-diff",
+  "api-diff-tool",
+  "breaking-change-detection",
+  "api-breaking-changes",
+  "prevent-breaking-api",
+  "api-regression",
+  "api-compatibility",
+  "contract-testing",
+  "consumer-driven-contract",
+  "api-contract",
+  "contract-verification",
+  "can-i-deploy",
+  "ci-cd",
+  "devops",
+  "github-actions",
+  "cli",
+  "developer-tools",
+  "openapi-compare",
+  "swagger-compare",
+  "pact-alternative",
+  "api-contract-testing",
+  "microservices",
+  "api-quality",
+  "api-governance",
+  "yaml",
+  "json"
+],
   "license": "MIT",
   "files": [
     "bin",

package/src/api/contractsClient.js

@@ -0,0 +1,88 @@
+'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 publishContract(server, apiToken, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post('/api/contracts/publish', payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function listContracts(server, apiToken, { org, consumer, provider, contractName, status, page = 0, size = 20 } = {}) {
+  try {
+    const params = { page, size };
+    if (org) params.orgKey = org;
+    if (consumer) params.consumerServiceKey = consumer;
+    if (provider) params.providerServiceKey = provider;
+    if (contractName) params.contractName = contractName;
+    if (status) params.status = status;
+    const res = await buildClient(server, apiToken).get('/api/contracts', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function getLatestContract(server, apiToken, { org, consumer, provider, contractName } = {}) {
+  try {
+    const params = {};
+    if (org) params.orgKey = org;
+    if (consumer) params.consumerServiceKey = consumer;
+    if (provider) params.providerServiceKey = provider;
+    if (contractName) params.contractName = contractName;
+    const res = await buildClient(server, apiToken).get('/api/contracts/latest', { params });
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function verifyContract(server, apiToken, contractId, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post(`/api/contracts/${contractId}/verify`, payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function getVerificationHistory(server, apiToken, contractId) {
+  try {
+    const res = await buildClient(server, apiToken).get(`/api/contracts/${contractId}/verifications`);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+async function canIDeploy(server, apiToken, { provider, version: ver, environment } = {}) {
+  try {
+    const params = { version: ver };
+    if (environment) params.environment = environment;
+    const res = await buildClient(server, apiToken).get(
+      `/api/providers/${encodeURIComponent(provider)}/can-i-deploy`, { params }
+    );
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
+module.exports = { publishContract, listContracts, getLatestContract, verifyContract, getVerificationHistory, canIDeploy };

package/src/cli.js

@@ -5,6 +5,7 @@ const { version } = require('../package.json');
 const compareCommand = require('./commands/compare');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
+const contractsCommand = require('./commands/contracts');
 
 const program = new Command();
 
@@ -16,6 +17,7 @@ program
 program.addCommand(compareCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
+program.addCommand(contractsCommand);
 
 program.parseAsync(process.argv).catch((err) => {
   const logger = require('./utils/logger');

package/src/commands/contracts.js

@@ -0,0 +1,561 @@
+'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 {
+  publishContract,
+  listContracts,
+  getLatestContract,
+  verifyContract,
+  getVerificationHistory,
+  canIDeploy,
+} = require('../api/contractsClient');
+
+// ─── 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 statusBadge(status) {
+  if (!status) return chalk.gray('—');
+  const s = String(status).toUpperCase();
+  if (s === 'PUBLISHED')  return chalk.green(s);
+  if (s === 'DEPRECATED') return chalk.yellow(s);
+  return chalk.gray(s);
+}
+
+function verifyBadge(status) {
+  if (!status) return chalk.gray('—');
+  const s = String(status).toUpperCase();
+  if (s === 'SUCCESS') return chalk.green(s);
+  if (s === 'FAILED')  return chalk.red(s);
+  if (s === 'PENDING') return chalk.yellow(s);
+  return chalk.gray(s);
+}
+
+function hr() {
+  return chalk.gray('  ─────────────────────────────────────────────────────');
+}
+
+/** 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');
+}
+
+/** Strip ANSI escape codes for length measurement */
+function stripAnsi(str) {
+  return str.replace(/\u001b\[[0-9;]*m/g, '');
+}
+
+// ─── Publish ─────────────────────────────────────────────────────────────────
+
+const publishCommand = new Command('publish')
+  .description('Publish a consumer contract to the registry')
+  .requiredOption('--file <path>', 'Path to contract JSON file')
+  .option('--org <key>', 'Organization key (overrides file value)')
+  .option('--consumer <key>', 'Consumer service key (overrides file value)')
+  .option('--provider <key>', 'Provider service key (overrides file value)')
+  .option('--consumer-version <ver>', 'Consumer version tag')
+  .option('--contract-name <name>', 'Contract name (overrides file value)')
+  .option('--tag <tag>', 'Tag / git branch')
+  .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);
+
+    // Read and validate file
+    const filePath = path.resolve(opts.file);
+    if (!(await fsExtra.pathExists(filePath))) {
+      logger.error(`Contract file not found: ${filePath}`);
+      process.exit(2);
+    }
+
+    let contractDoc;
+    try {
+      const raw = await fsExtra.readFile(filePath, 'utf8');
+      contractDoc = JSON.parse(raw);
+    } catch (err) {
+      logger.error(`Invalid JSON in contract file: ${err.message}`);
+      process.exit(2);
+    }
+
+    // Basic schema validation
+    if (!contractDoc.interactions || !Array.isArray(contractDoc.interactions)) {
+      logger.error('Contract file must have an "interactions" array.');
+      process.exit(2);
+    }
+
+    // Resolve metadata (CLI flags override file values)
+    const orgKey        = opts.org          || contractDoc.orgKey          || contractDoc.org;
+    const consumerKey   = opts.consumer     || contractDoc.consumer?.name;
+    const providerKey   = opts.provider     || contractDoc.provider?.name;
+    const contractName  = opts.contractName || contractDoc.contractName;
+    const contractType  = contractDoc.contractType || 'HTTP';
+
+    const missing = [];
+    if (!orgKey)       missing.push('--org (or "org" in contract file)');
+    if (!consumerKey)  missing.push('--consumer (or consumer.name in contract file)');
+    if (!providerKey)  missing.push('--provider (or provider.name in contract file)');
+    if (!contractName) missing.push('--contract-name (or contractName in contract file)');
+    if (missing.length) {
+      logger.error(`Missing required fields:\n    ${missing.join('\n    ')}`);
+      process.exit(2);
+    }
+
+    const spinner = ora('Publishing contract...').start();
+
+    try {
+      const result = await publishContract(opts.server, token, {
+        orgKey,
+        consumerServiceKey: consumerKey,
+        providerServiceKey: providerKey,
+        consumerVersion:    opts.consumerVersion || contractDoc.consumer?.version || null,
+        contractName,
+        contractType,
+        gitBranch:          opts.tag || null,
+        verifierName:       'specshield-cli',
+        contentJson:        contractDoc,
+      });
+      spinner.stop();
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.green.bold('  ✔  Contract Published Successfully') + '\n');
+      process.stdout.write(hr() + '\n');
+      process.stdout.write(`  Contract ID     : ${chalk.cyan(result.contractId)}\n`);
+      process.stdout.write(`  Contract Name   : ${chalk.white(contractName)}\n`);
+      process.stdout.write(`  Consumer        : ${consumerKey}\n`);
+      process.stdout.write(`  Provider        : ${providerKey}\n`);
+      process.stdout.write(`  Version         : ${chalk.cyan(result.contractVersion)}\n`);
+      process.stdout.write(`  Status          : ${statusBadge(result.status)}\n`);
+      if (result.contentHash) {
+        process.stdout.write(`  Content Hash    : ${chalk.gray(result.contentHash.substring(0, 16) + '...')}\n`);
+      }
+      process.stdout.write(`  Published At    : ${fmtDate(result.publishedAt)}\n`);
+      process.stdout.write('\n');
+      process.stdout.write(chalk.gray(`  ➜  Run: specshield contracts verify --contract-id ${result.contractId} --base-url <URL>\n`));
+      process.stdout.write('\n');
+    } catch (err) {
+      spinner.fail('Publish failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── List ─────────────────────────────────────────────────────────────────────
+
+const listCommand = new Command('list')
+  .description('List contracts in the registry')
+  .option('--consumer <key>', 'Filter by consumer service key')
+  .option('--provider <key>', 'Filter by provider service key')
+  .option('--org <key>', 'Filter by organization key')
+  .option('--status <status>', 'Filter by status (PUBLISHED | DEPRECATED)')
+  .option('--contract-name <name>', 'Filter by contract 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 contracts...').start();
+
+    try {
+      const page = await listContracts(opts.server, token, {
+        org:          opts.org,
+        consumer:     opts.consumer,
+        provider:     opts.provider,
+        contractName: opts.contractName,
+        status:       opts.status,
+        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 || [];
+      const total = page.totalElements ?? items.length;
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold('  SpecShield Contract Registry') + '\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 contracts found matching filters.\n\n'));
+        return;
+      }
+
+      printTable(
+        ['ID', 'Contract Name', 'Consumer', 'Provider', 'Ver', 'Status', 'Last Verify', 'Published'],
+        items.map(c => [
+          chalk.cyan(String(c.contractId)),
+          c.contractName,
+          c.consumerServiceKey,
+          c.providerServiceKey,
+          c.contractVersion,
+          statusBadge(c.status),
+          verifyBadge(c.lastVerificationStatus),
+          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);
+    }
+  });
+
+// ─── Latest ───────────────────────────────────────────────────────────────────
+
+const latestCommand = new Command('latest')
+  .description('Get the latest version of a contract')
+  .option('--consumer <key>', 'Consumer service key')
+  .option('--provider <key>', 'Provider service key')
+  .option('--org <key>', 'Organization key')
+  .option('--contract-name <name>', 'Contract name')
+  .option('--json', 'Print full contract 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 latest contract...').start();
+
+    try {
+      const c = await getLatestContract(opts.server, token, {
+        org:          opts.org,
+        consumer:     opts.consumer,
+        provider:     opts.provider,
+        contractName: opts.contractName,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(c, null, 2) + '\n');
+        return;
+      }
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold('  Latest Contract') + '\n');
+      process.stdout.write(hr() + '\n');
+      process.stdout.write(`  Contract ID     : ${chalk.cyan(c.contractId)}\n`);
+      process.stdout.write(`  Contract Name   : ${chalk.white(c.contractName)}\n`);
+      process.stdout.write(`  Consumer        : ${c.consumerServiceKey}\n`);
+      process.stdout.write(`  Provider        : ${c.providerServiceKey}\n`);
+      process.stdout.write(`  Version         : ${chalk.cyan(c.contractVersion)}\n`);
+      process.stdout.write(`  Type            : ${c.contractType || '—'}\n`);
+      process.stdout.write(`  Status          : ${statusBadge(c.status)}\n`);
+      if (c.contentHash) {
+        process.stdout.write(`  Content Hash    : ${chalk.gray(c.contentHash.substring(0, 16) + '...')}\n`);
+      }
+      process.stdout.write(`  Published At    : ${fmtDate(c.publishedAt)}\n`);
+
+      if (c.verificationHistory && c.verificationHistory.length) {
+        const last = c.verificationHistory[0];
+        process.stdout.write('\n');
+        process.stdout.write(chalk.bold('  Last Verification') + '\n');
+        process.stdout.write(hr() + '\n');
+        process.stdout.write(`  Verification ID : ${chalk.cyan(last.verificationId)}\n`);
+        process.stdout.write(`  Status          : ${verifyBadge(last.verificationStatus)}\n`);
+        process.stdout.write(`  Environment     : ${last.environment || '—'}\n`);
+        process.stdout.write(`  Provider Ver    : ${last.providerVersion || '—'}\n`);
+        process.stdout.write(`  Completed At    : ${fmtDate(last.completedAt)}\n`);
+      }
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.gray(`  ➜  Use --json to see full contract content\n`));
+      process.stdout.write(chalk.gray(`  ➜  Run: specshield contracts verify --contract-id ${c.contractId} --base-url <URL>\n`));
+      process.stdout.write('\n');
+    } catch (err) {
+      if (spinner) spinner.fail('Fetch failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── Verify ───────────────────────────────────────────────────────────────────
+
+const verifyCommand = new Command('verify')
+  .description('Verify a contract against a live provider')
+  .requiredOption('--contract-id <id>', 'Contract ID to verify')
+  .requiredOption('--base-url <url>', 'Provider base URL (e.g. http://localhost:8080)')
+  .option('--provider-version <ver>', 'Provider version tag')
+  .option('--env <environment>', 'Environment label (e.g. staging, qa)')
+  .option('--mode <mode>', 'Verification mode: LIVE | REPLAY', 'LIVE')
+  .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);
+
+    // Validate base URL
+    try { new URL(opts.baseUrl); } catch {
+      logger.error(`Invalid base URL: ${opts.baseUrl}`);
+      process.exit(2);
+    }
+
+    const contractId = parseInt(opts.contractId, 10);
+    if (isNaN(contractId)) {
+      logger.error('--contract-id must be a number');
+      process.exit(2);
+    }
+
+    const spinner = opts.json ? null : ora(`Verifying contract ${contractId}...`).start();
+
+    try {
+      const result = await verifyContract(opts.server, token, contractId, {
+        baseUrl:         opts.baseUrl.replace(/\/$/, ''),
+        providerVersion: opts.providerVersion || null,
+        verificationMode: opts.mode || 'LIVE',
+        environment:     opts.env || null,
+        verifierName:    'specshield-cli',
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        return;
+      }
+
+      const summary   = result.summary || {};
+      const total     = summary.total   ?? 0;
+      const passed    = summary.passed  ?? 0;
+      const failed    = summary.failed  ?? 0;
+      const mismatches = result.mismatches || [];
+      const success   = result.verificationStatus === 'SUCCESS';
+
+      process.stdout.write('\n');
+      if (success) {
+        process.stdout.write(chalk.green.bold(`  ✔  Verification PASSED`) + chalk.gray(`  (${passed}/${total} interactions)\n`));
+      } else {
+        process.stdout.write(chalk.red.bold(`  ✖  Verification FAILED`) + chalk.gray(`  (${passed}/${total} interactions passed, ${failed} failed)\n`));
+      }
+      process.stdout.write(hr() + '\n');
+      process.stdout.write(`  Verification ID : ${chalk.cyan(result.verificationId)}\n`);
+      process.stdout.write(`  Contract ID     : ${chalk.cyan(contractId)}\n`);
+      process.stdout.write(`  Status          : ${verifyBadge(result.verificationStatus)}\n`);
+      process.stdout.write(`  Started At      : ${fmtDate(result.startedAt)}\n`);
+      process.stdout.write(`  Completed At    : ${fmtDate(result.completedAt)}\n`);
+
+      if (mismatches.length > 0) {
+        process.stdout.write('\n');
+        process.stdout.write(chalk.red.bold('  Mismatches') + '\n');
+        process.stdout.write(hr() + '\n');
+        for (const m of mismatches) {
+          process.stdout.write(`  ${chalk.red('●')} ${chalk.bold('[' + (m.interactionKey || '?') + ']')} ${chalk.yellow(m.mismatchType)} at ${chalk.gray(m.path || '$')}\n`);
+          if (m.expectedValue !== null && m.expectedValue !== undefined) {
+            process.stdout.write(`    ${chalk.gray('expected:')} ${chalk.green(m.expectedValue)}  ${chalk.gray('→')}  ${chalk.red(m.actualValue ?? 'null')}\n`);
+          }
+          process.stdout.write(`    ${chalk.gray(m.message || '')}\n`);
+        }
+        process.stdout.write('\n');
+      }
+
+      if (success) {
+        process.stdout.write(chalk.gray(`  ➜  Run: specshield contracts can-i-deploy --provider <NAME> --version <VER>\n`));
+      } else {
+        process.stdout.write(chalk.gray(`  ➜  Run: specshield contracts history --contract-id ${contractId} to inspect past runs\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);
+    }
+  });
+
+// ─── History ──────────────────────────────────────────────────────────────────
+
+const historyCommand = new Command('history')
+  .description('Show verification history for a contract')
+  .requiredOption('--contract-id <id>', 'Contract ID')
+  .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 contractId = parseInt(opts.contractId, 10);
+    if (isNaN(contractId)) {
+      logger.error('--contract-id must be a number');
+      process.exit(2);
+    }
+
+    const spinner = opts.json ? null : ora('Fetching verification history...').start();
+
+    try {
+      const history = await getVerificationHistory(opts.server, token, contractId);
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(history, null, 2) + '\n');
+        return;
+      }
+
+      const items = Array.isArray(history) ? history : (history.content || []);
+
+      process.stdout.write('\n');
+      process.stdout.write(chalk.bold(`  Verification History — Contract ${contractId}`) + '\n');
+      process.stdout.write(hr() + '\n');
+
+      if (items.length === 0) {
+        process.stdout.write(chalk.gray('\n  No verifications found for this contract.\n\n'));
+        return;
+      }
+
+      printTable(
+        ['ID', 'Status', 'Environment', 'Provider Version', 'Mode', 'Completed At'],
+        items.map(v => [
+          chalk.cyan(String(v.verificationId ?? v.id ?? '—')),
+          verifyBadge(v.verificationStatus),
+          v.environment || '—',
+          v.providerVersion || '—',
+          v.verificationMode || '—',
+          fmtDate(v.completedAt),
+        ])
+      );
+
+      process.stdout.write(chalk.gray(`  ➜  Run: specshield contracts verify --contract-id ${contractId} --base-url <URL> to re-verify\n\n`));
+    } catch (err) {
+      if (spinner) spinner.fail('Fetch failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// ─── Can-I-Deploy ─────────────────────────────────────────────────────────────
+
+const canIDeployCommand = new Command('can-i-deploy')
+  .description('Check if a provider version is safe to deploy')
+  .requiredOption('--provider <key>', 'Provider service key')
+  .requiredOption('--version <ver>', 'Provider version to check')
+  .option('--env <environment>', 'Target environment (e.g. qa, staging, production)')
+  .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.provider}@${opts.version}...`).start();
+
+    try {
+      const results = await canIDeploy(opts.server, token, {
+        provider:    opts.provider,
+        version:     opts.version,
+        environment: opts.env || null,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+        return;
+      }
+
+      const items = Array.isArray(results) ? results : [results];
+      const allAllowed = items.every(r => r.allowed);
+      const envLabel = opts.env ? ` in ${opts.env}` : '';
+
+      process.stdout.write('\n');
+      if (allAllowed) {
+        process.stdout.write(chalk.green.bold('  ✔  PASS') + chalk.white(`: ${opts.provider} v${opts.version} is deployable${envLabel}\n`));
+      } else {
+        process.stdout.write(chalk.red.bold('  ✖  FAIL') + chalk.white(`: ${opts.provider} v${opts.version} is NOT deployable${envLabel}\n`));
+      }
+      process.stdout.write(hr() + '\n');
+
+      if (items.length > 0) {
+        process.stdout.write('\n');
+        process.stdout.write(chalk.bold('  Contract Decisions') + '\n');
+        for (const r of items) {
+          const icon = r.allowed ? chalk.green('✔') : chalk.red('✖');
+          const status = r.verificationStatus
+            ? ` — ${verifyBadge(r.verificationStatus)}`
+            : '';
+          process.stdout.write(`  ${icon} Contract ID ${chalk.cyan(r.contractId)}${status}\n`);
+          if (r.reason) {
+            process.stdout.write(`    ${chalk.gray(r.reason)}\n`);
+          }
+        }
+        process.stdout.write('\n');
+      }
+
+      if (!allAllowed) {
+        process.stdout.write(chalk.gray(`  ➜  Run: specshield contracts verify --contract-id <ID> --base-url <URL>\n`));
+        process.stdout.write(chalk.gray(`  ➜  to verify pending contracts before deploying\n`));
+      }
+      process.stdout.write('\n');
+
+      process.exit(allAllowed ? 0 : 1);
+    } catch (err) {
+      if (spinner) spinner.fail('Check failed');
+      logger.error(err.message);
+      process.exit(2);
+    }
+  });
+
+// ─── Parent contracts command ─────────────────────────────────────────────────
+
+const contracts = new Command('contracts')
+  .description('Manage and verify consumer-driven contracts');
+
+contracts.addCommand(publishCommand);
+contracts.addCommand(listCommand);
+contracts.addCommand(latestCommand);
+contracts.addCommand(verifyCommand);
+contracts.addCommand(historyCommand);
+contracts.addCommand(canIDeployCommand);
+
+module.exports = contracts;