specshield 2.0.1 → 3.1.1

package/README.md

@@ -7,7 +7,7 @@
 
 ---
 
-> **OpenAPI Diff · API Breaking Change Detection · Swagger Diff · Consumer-Driven Contract Testing · Pact Alternative · can-i-deploy · Bi-Directional Contract Testing · GitHub PR Checks · CI/CD**
+> **OpenAPI Diff · API Breaking Change Detection · Swagger Diff · Bi-Directional Contract Testing · Pact Alternative · can-i-deploy · GitHub PR Checks · CI/CD**
 
 ---
 
@@ -57,7 +57,7 @@ No runtime surprise. No production incident. No 3am page.
 
 [![SpecShield Demo — API Breaking Change Detection & Contract Testing](https://img.youtube.com/vi/mugDyQQGqZw/maxresdefault.jpg)](https://www.youtube.com/watch?v=mugDyQQGqZw)
 
-> Watch: Catching a breaking API change before it hits production — compare specs, publish contracts, verify providers, and gate deployments with `can-i-deploy`.
+> Watch: Catching a breaking API change before it hits production — compare specs, publish provider/consumer specs via BDCT, and gate deployments with `can-i-deploy`.
 
 **CLI preview:**
 
@@ -117,6 +117,26 @@ specshield compare base.yaml target.yaml --fail-on-breaking
 
 That's it. Works with any OpenAPI 3.x YAML or JSON spec.
 
+**For BDCT**, run the wizard once and never re-type the same flags again:
+
+```bash
+specshield init
+```
+
+It autodetects your OpenAPI spec, your service name (from `package.json` /
+`pyproject.toml` / `pom.xml` / `go.mod`), your git branch, and your
+default environment, asks you a few questions, and writes a
+**`.specshield.yml`** at the project root. Every subsequent
+`specshield bdct ...` invocation reads this file, so your CI commands
+collapse to:
+
+```bash
+specshield bdct publish-provider --version $GITHUB_SHA
+specshield bdct can-i-deploy --version $GITHUB_SHA
+```
+
+See [§ specshield init](#specshield-init--first-run-setup-wizard) below.
+
 ---
 
 ## 🚀 Create Your Free Account
@@ -141,8 +161,6 @@ That's it. Works with any OpenAPI 3.x YAML or JSON spec.
 | 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** | ❌ | ❌ | ✅ |
@@ -160,8 +178,9 @@ That's it. Works with any OpenAPI 3.x YAML or JSON spec.
 > Without SpecShield, this would have reached staging, broken checkout for every user,
 > and triggered an incident at 2am.
 >
-> With SpecShield, the provider's CI ran `specshield contracts verify` against the
-> consumer's published contract. The mismatch was caught immediately:
+> With SpecShield, the provider's CI published the new spec via
+> `specshield bdct publish-provider`. The compatibility engine ran against
+> `checkout-ui`'s published contract and the mismatch was caught immediately:
 >
 > ```
 > ● MISSING_FIELD at $.status
@@ -195,7 +214,6 @@ Track API drift over time across your entire platform. Know what changed, when,
 |---|---|---|---|
 | OpenAPI / Swagger native | ✅ | ❌ (code-level) | ✅ |
 | No broker required | ✅ | ❌ (needs Pact Broker) | ✅ |
-| Consumer-driven contract testing | ✅ | ✅ | ❌ |
 | **Bi-directional contract testing** | ✅ | ✅ (Pactflow paid) | ❌ |
 | Breaking change detection | ✅ | ❌ | ✅ |
 | can-i-deploy gating | ✅ | ✅ (via broker) | ❌ |
@@ -212,7 +230,7 @@ Track API drift over time across your entire platform. Know what changed, when,
 
 | Plan | Price | What's included |
 |---|---|---|
-| **Free** | $0 forever | Local compare (unlimited) · Compare history & dashboard · CDCT contracts & can-i-deploy · GitHub App PR checks |
+| **Free** | $0 forever | Local compare (unlimited) · Compare history & dashboard · 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.
@@ -351,116 +369,80 @@ github:
 
 ---
 
-## Contract Testing (CDCT)
-
-Consumer-driven contract testing for microservices — without a broker.
+## `specshield init` — first-run setup wizard
 
-**How it works:**
+Run once at the root of your project. The wizard:
 
-1. Consumer team publishes a contract (what they expect from the provider)
-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
-
-```json
-{
-  "consumer": { "name": "checkout-ui", "version": "2.0.0" },
-  "provider": { "name": "payment-service" },
-  "orgKey": "acme-store",
-  "contractName": "create-payment",
-  "contractType": "HTTP",
-  "interactions": [
-    {
-      "description": "checkout-ui creates a payment",
-      "request": {
-        "method": "POST",
-        "path": "/payments",
-        "headers": { "Content-Type": "application/json" },
-        "body": { "orderId": "ORD-123", "amount": 1299, "currency": "INR" }
-      },
-      "expectedResponse": {
-        "status": 201,
-        "headers": { "Content-Type": "application/json" },
-        "body": { "paymentId": "PAY-123", "status": "CREATED" }
-      }
-    }
-  ]
-}
-```
-
-### Publish a Contract
+1. Detects your OpenAPI spec (looks under `api/`, `spec/`, `docs/`, repo root).
+2. Detects your service name (`package.json`, `pyproject.toml`, `pom.xml`, `go.mod`, `Cargo.toml`, or directory name).
+3. Detects your git branch and suggests `production` for `main`/`master`, `staging` otherwise.
+4. Asks whether this project is a provider, a consumer, or both.
+5. Asks for your org key (autocompletes from your account if you're already signed in).
+6. Validates / stores your API key.
+7. Writes **`.specshield.yml`** and, optionally, a starter **`.github/workflows/specshield-bdct.yml`** that uses [`specshield26/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct).
 
 ```bash
-specshield contracts publish \
-  --file ./contracts/create-payment.json \
-  --org acme-store \
-  --consumer-version 2.0.0 \
-  --tag main
+specshield init
 ```
 
-### Verify a Contract
+### Example `.specshield.yml`
 
-```bash
-specshield contracts verify \
-  --contract-id 42 \
-  --base-url http://localhost:8080 \
-  --provider-version v2.1.0 \
-  --env staging
-```
-
-Pass output:
-```
-  ✔  Verification PASSED  (1/1 interactions)
-```
+```yaml
+schemaVersion: 1
 
-Fail output:
-```
-  ✖  Verification FAILED  (0/1 interactions passed, 1 failed)
+failOnBreaking: true
+severity: error
 
-  Mismatches
-  ● [create payment] MISSING_FIELD at $.status
-    expected: "CREATED"  →  actual: null
-```
+bdct:
+  org: acme-pay
+  environment: staging
 
-### Can I Deploy?
+  provider:
+    name: payment-service
+    spec: api/openapi.yaml
 
-```bash
-specshield contracts can-i-deploy \
-  --provider payment-service \
-  --version v2.1.0 \
-  --env staging
-```
+  # consumer (optional — present when --kind=consumer or --kind=both):
+  # consumer:
+  #   name: checkout-ui
+  #   provider: payment-service
+  #   contract: contracts/payment-service.yaml
+  #   format: OPENAPI
 
-```
-  ✔  PASS: payment-service v2.1.0 is deployable in staging
-```
-```
-  ✖  FAIL: payment-service v2.1.0 is NOT deployable in staging
+github:
+  specPath: api/openapi.yaml
+  failOnBreaking: true
+  commentOnPr: true
 ```
 
-Exit codes: `0` = deployable · `1` = blocked · `2` = error
+CLI flags **always** override this file. Paths in the file are resolved
+relative to the file's own directory, so you can run `specshield bdct ...`
+from any subdirectory of your project.
 
-### List and Inspect Contracts
+### Non-interactive (scriptable) mode
 
 ```bash
-specshield contracts list --provider payment-service
-specshield contracts latest --consumer checkout-ui --provider payment-service --json
-specshield contracts history --contract-id 42
+specshield init --no-interactive \
+  --kind     provider \
+  --org      acme-pay \
+  --provider payment-service \
+  --spec     api/openapi.yaml \
+  --env      staging \
+  --write-workflow
 ```
 
-### Full CDCT Workflow
+### Other useful flags
 
-```bash
-# 1. Consumer publishes contract
-specshield contracts publish --file ./contracts/create-payment.json --org acme-store
-
-# 2. Provider verifies it
-specshield contracts verify --contract-id 42 --base-url http://localhost:8080 --provider-version v2.1.0
+| Flag | Purpose |
+| --- | --- |
+| `--print` | Detect everything, print the proposed YAML, write nothing. Good for `--dry-run` review in CI. |
+| `--force` | Skip the overwrite-confirmation if `.specshield.yml` already exists. |
+| `--server <url>` | Use a non-default SpecShield endpoint (self-hosted / staging). |
+| `--write-workflow` | Also write a starter GitHub Actions workflow under `.github/workflows/`. |
 
-# 3. Gate the deployment
-specshield contracts can-i-deploy --provider payment-service --version v2.1.0
-```
+> **What is _not_ written into `.specshield.yml`:** your API key. It is
+> stored in `~/.specshield/config.json` (set by `specshield login`) or
+> read from `SPECSHIELD_API_KEY` in CI. The project file is meant to be
+> committed; never commit a secret into it.
 
 ---
 
@@ -468,20 +450,12 @@ specshield contracts can-i-deploy --provider payment-service --version v2.1.0
 
 **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.
+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. Pact JSON consumer contracts are also accepted and auto-converted.
 
 > 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)
@@ -687,7 +661,7 @@ specshield bdct list-consumers --org acme-store --provider payment-service
 ### List Verifications
 
 ```bash
-specshield bdct list-verifications \
+specshield bdct list \
   --org acme-store \
   --provider payment-service \
   --env production \
@@ -780,73 +754,6 @@ jobs:
         run: specshield compare /tmp/base.yaml api/openapi.yaml --fail-on-breaking
 ```
 
-### On Push — Publish consumer contract (CDCT)
-
-```yaml
-name: Publish Contract
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'contracts/**'
-
-jobs:
-  publish:
-    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-store \
-            --tag ${{ github.ref_name }}
-```
-
-### On Push — Verify provider + gate deployment (CDCT)
-
-```yaml
-name: Contract Verification
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  verify:
-    runs-on: ubuntu-latest
-    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.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
-```
-
 ### On Push — Publish provider spec (BDCT)
 
 ```yaml
@@ -981,7 +888,7 @@ specshield bdct <subcommand> [options]
 | `matrix` | View compatibility matrix across all pairs |
 | `list-providers` | List published provider specs |
 | `list-consumers` | List published consumer contracts |
-| `list-verifications` | List verification history |
+| `list` | List verification history |
 
 All `bdct` subcommands support `--json` for machine-readable output.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specshield",
-  "version": "2.0.1",
-  "description": "CLI for OpenAPI breaking change detection, consumer-driven contract testing, and bi-directional contract verification — with can-i-deploy gating and GitHub PR checks.",
+  "version": "3.1.1",
+  "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating, GitHub PR checks, and a first-run setup wizard.",
   "main": "src/cli.js",
   "bin": {
     "specshield": "./bin/specshield.js"
@@ -13,36 +13,36 @@
     "lint": "eslint src tests --ext .js"
   },
   "keywords": [
-  "openapi",
-  "swagger",
-  "api-diff",
-  "openapi-diff",
-  "swagger-diff",
-  "breaking-change-detection",
-  "api-breaking-changes",
-  "api-compatibility",
-  "contract-testing",
-  "consumer-driven-contract",
-  "api-contract",
-  "contract-verification",
-  "can-i-deploy",
-  "ci-cd",
-  "github-actions",
-  "cli",
-  "developer-tools",
-  "openapi-compare",
-  "swagger-compare",
-  "pact-alternative",
-  "api-contract-testing",
-  "microservices",
-  "api-quality",
-  "api-governance",
-  "bi-directional-contract-testing",
-  "bdct",
-  "pact-json",
-  "github-app",
-  "api-drift"
-],
+    "openapi",
+    "swagger",
+    "api-diff",
+    "openapi-diff",
+    "swagger-diff",
+    "breaking-change-detection",
+    "api-breaking-changes",
+    "api-compatibility",
+    "contract-testing",
+    "consumer-driven-contract",
+    "api-contract",
+    "contract-verification",
+    "can-i-deploy",
+    "ci-cd",
+    "github-actions",
+    "cli",
+    "developer-tools",
+    "openapi-compare",
+    "swagger-compare",
+    "pact-alternative",
+    "api-contract-testing",
+    "microservices",
+    "api-quality",
+    "api-governance",
+    "bi-directional-contract-testing",
+    "bdct",
+    "pact-json",
+    "github-app",
+    "api-drift"
+  ],
   "license": "MIT",
   "files": [
     "bin",
@@ -56,7 +56,8 @@
     "commander": "^12.0.0",
     "fs-extra": "^11.2.0",
     "js-yaml": "^4.1.0",
-    "ora": "^5.4.1"
+    "ora": "^5.4.1",
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/src/api/bdctClient.js

@@ -22,7 +22,10 @@ function apiError(err) {
     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}`);
+    const e = new Error(`API error (${err.response.status}): ${msg}`);
+    e.status = err.response.status;
+    e.responseData = data;
+    return e;
   }
   if (err.request) return new Error(`No response from server: ${err.message}`);
   return new Error(`Request failed: ${err.message}`);
@@ -51,11 +54,10 @@ async function verify(server, apiToken, payload) {
 
 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 params = { orgKey: org, page, size };
+    if (consumer) params.consumerName = consumer;
+    if (provider) params.providerName = provider;
+    if (env)      params.environment = env;
     const res = await buildClient(server, apiToken).get('/api/bdct/verifications', { params });
     return res.data;
   } catch (err) { throw apiError(err); }
@@ -63,41 +65,44 @@ async function listVerifications(server, apiToken, { org, consumer, provider, en
 
 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 params = { orgKey: org, service, version: ver };
+    if (env) params.environment = env;
     const res = await buildClient(server, apiToken).get('/api/bdct/can-i-deploy', { params });
     return res.data;
-  } catch (err) { throw apiError(err); }
+  } catch (err) {
+    // 409 = NOT DEPLOYABLE — valid result, not an error (backend signals via status)
+    if (err.response && err.response.status === 409 && err.response.data
+        && typeof err.response.data === 'object'
+        && Object.prototype.hasOwnProperty.call(err.response.data, 'deployable')) {
+      return err.response.data;
+    }
+    throw apiError(err);
+  }
 }
 
 async function getMatrix(server, apiToken, { org, env } = {}) {
   try {
-    const params = {};
-    if (org) params.orgKey = org;
-    if (env) params.env = env;
+    const params = { orgKey: org };
+    if (env) params.environment = 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 } = {}) {
+async function listProviderSpecs(server, apiToken, { org, provider } = {}) {
   try {
-    const params = { page, size };
-    if (org)      params.orgKey = org;
-    if (provider) params.provider = provider;
-    if (env)      params.env = env;
+    const params = { orgKey: org };
+    if (provider) params.providerName = provider;
     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 } = {}) {
+async function listConsumerContracts(server, apiToken, { org, consumer, provider } = {}) {
   try {
-    const params = { page, size };
-    if (org)      params.orgKey = org;
-    if (consumer) params.consumer = consumer;
-    if (provider) params.provider = provider;
+    const params = { orgKey: org };
+    if (consumer) params.consumerName = consumer;
+    if (provider) params.providerName = provider;
     const res = await buildClient(server, apiToken).get('/api/bdct/consumer-contracts', { params });
     return res.data;
   } catch (err) { throw apiError(err); }

package/src/cli.js

@@ -3,9 +3,9 @@
 const { Command } = require('commander');
 const { version } = require('../package.json');
 const compareCommand = require('./commands/compare');
+const initCommand = require('./commands/init');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
-const contractsCommand = require('./commands/contracts');
 const bdctCommand = require('./commands/bdct');
 
 const program = new Command();
@@ -13,12 +13,16 @@ const program = new Command();
 program
   .name('specshield')
   .description('Compare OpenAPI specs and detect breaking changes')
-  .version(version);
+  .version(version)
+  // Without this, a subcommand option named `--version` (e.g. on `bdct can-i-deploy`)
+  // is greedily consumed by the root `--version` flag and the program prints the
+  // CLI version and exits before the subcommand runs.
+  .enablePositionalOptions();
 
 program.addCommand(compareCommand);
+program.addCommand(initCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
-program.addCommand(contractsCommand);
 program.addCommand(bdctCommand);
 
 program.parseAsync(process.argv).catch((err) => {