specshield 3.0.0 → 3.1.2

package/README.md

@@ -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
@@ -248,7 +268,16 @@ Done. Your token is stored in `~/.specshield/config.json` — no need to pass it
 export SPECSHIELD_API_KEY=ss_your_token_here
 ```
 
-Token resolution order: `--api-key flag` → `SPECSHIELD_API_KEY` env var → stored config → `.specshield.yml`
+This single env var works for every command — `compare`, `login`, and every
+`bdct` subcommand all read it.
+
+Token resolution order:
+- `compare` / `login`: `--api-key` flag → `SPECSHIELD_API_KEY` env var → stored config → `.specshield.yml`
+- `bdct ...` subcommands: `--api-token` flag → `SPECSHIELD_API_KEY` env var → stored config
+
+> **Why two flag names?** `compare` and `login` were built first and used
+> `--api-key`. The newer `bdct` commands use `--api-token` to keep the word
+> "key" reserved for the stored config concept. The env var unifies both.
 
 ---
 
@@ -349,6 +378,104 @@ github:
 
 ---
 
+## `specshield init` — first-run setup wizard
+
+Run once at the root of your project. The wizard:
+
+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 init
+```
+
+### Example `.specshield.yml`
+
+```yaml
+schemaVersion: 1
+
+failOnBreaking: true
+severity: error
+
+bdct:
+  org: acme-pay
+  environment: staging
+
+  provider:
+    name: payment-service
+    spec: api/openapi.yaml
+
+  # consumer (optional — present when --kind=consumer or --kind=both):
+  # consumer:
+  #   name: checkout-ui
+  #   provider: payment-service
+  #   contract: contracts/payment-service.yaml
+  #   format: OPENAPI
+
+github:
+  specPath: api/openapi.yaml
+  failOnBreaking: true
+  commentOnPr: true
+```
+
+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.
+
+### Non-interactive (scriptable) mode
+
+```bash
+# Provider-only project
+specshield init --no-interactive \
+  --kind     provider \
+  --org      acme-pay \
+  --provider payment-service \
+  --spec     api/openapi.yaml \
+  --env      staging \
+  --write-workflow
+
+# Consumer-only project
+specshield init --no-interactive \
+  --kind              consumer \
+  --org               acme-pay \
+  --consumer          checkout-ui \
+  --consumer-provider payment-service \
+  --contract          contracts/payment-service.yaml \
+  --format            OPENAPI \
+  --env               staging
+```
+
+### All `init` flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--no-interactive` | Run without prompts; all required fields must come from flags or `package.json`/git autodetection. |
+| `--print` | Detect everything, print the proposed YAML to stdout, 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). Default: `https://specshield.io`. |
+| `--kind <kind>` | `provider`, `consumer`, `both`, or `skip`. Required in `--no-interactive`. |
+| `--org <key>` | Organization key. |
+| `--provider <name>` | Provider service name (used when `--kind=provider|both`). |
+| `--spec <path>` | Path to the provider OpenAPI spec. |
+| `--consumer <name>` | Consumer service name (used when `--kind=consumer|both`). |
+| `--consumer-provider <name>` | The provider this consumer talks to (used when `--kind=consumer|both`). |
+| `--contract <path>` | Path to the consumer contract (OpenAPI or Pact JSON). |
+| `--format <fmt>` | Consumer contract format: `OPENAPI` (default) or `PACT`. |
+| `--env <environment>` | Default environment for BDCT operations. |
+| `--write-workflow` | Also write a starter GitHub Actions workflow under `.github/workflows/specshield-bdct.yml`. |
+
+> **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.
+
+---
+
 ## Bi-Directional Contract Testing (BDCT)
 
 **Spec-to-spec contract testing — no running services required.**
@@ -374,17 +501,25 @@ specshield bdct publish-provider \
   --provider payment-service \
   --version v2.1.0 \
   --spec ./api/openapi.yaml \
-  --env production
+  --env production \
+  --branch main
 ```
 
 ```
-  ✔  Provider spec published
-     Provider  : payment-service
-     Version   : v2.1.0
-     Env       : production
-     Auto-verifications triggered: 3
+  ✔  Provider Spec Published
+  ─────────────────────────────────────────────────────
+  ID          : 1842
+  Provider    : payment-service
+  Version     : v2.1.0
+  Environment : production
+  Published At: 2026-05-13 14:30:12
+  Verifications triggered: 3
 ```
 
+`--branch` is optional — when present it's stamped on the published spec so you
+can correlate a spec version with the git branch it came from in
+`bdct list-providers`.
+
 ### Publish a Consumer Contract
 
 The consumer contract is an OpenAPI spec that describes only the endpoints the consumer uses:
@@ -425,19 +560,30 @@ specshield bdct publish-consumer \
   --consumer checkout-ui \
   --provider payment-service \
   --version 2.0.0 \
-  --contract ./contracts/checkout-ui-payment.yaml
+  --contract ./contracts/checkout-ui-payment.yaml \
+  --format OPENAPI
 ```
 
 ```
-  ✔  Consumer contract published
-     Consumer    : checkout-ui @ 2.0.0
-     Provider    : payment-service
-     Compatibility: COMPATIBLE
+  ✔  Consumer Contract Published
+  ─────────────────────────────────────────────────────
+  ID          : 942
+  Consumer    : checkout-ui
+  Provider    : payment-service
+  Version     : 2.0.0
+  Format      : OPENAPI
+  Published At: 2026-05-13 14:31:05
+  Verifications triggered: 1
+
+  ➜  Run: specshield bdct verify --consumer checkout-ui --provider payment-service
 ```
 
-If the provider spec is already published, compatibility is checked immediately.
+If the provider spec is already published, compatibility is verified
+automatically — the "Verifications triggered" count reflects that.
 
-**Pact JSON contracts are also accepted** — SpecShield auto-converts them:
+**Pact JSON contracts are also supported** — pass `--format PACT` and point
+`--contract` at a Pact file. The backend stores the format and runs the same
+compatibility engine against your provider's OpenAPI spec:
 
 ```bash
 specshield bdct publish-consumer \
@@ -445,9 +591,12 @@ specshield bdct publish-consumer \
   --consumer checkout-ui \
   --provider payment-service \
   --version 2.0.0 \
-  --contract ./pacts/checkout-ui-payment-service.json
+  --contract ./pacts/checkout-ui-payment-service.json \
+  --format PACT
 ```
 
+`--format` defaults to `OPENAPI` if omitted.
+
 ### Verify Compatibility
 
 Manually trigger a verification between a specific consumer/provider pair:
@@ -499,18 +648,36 @@ specshield bdct can-i-deploy \
   --env production
 ```
 
+Deployable output:
+
 ```
-  ✔  DEPLOYABLE
+  ✔  PASS: payment-service v2.1.0 is deployable in production
+  ─────────────────────────────────────────────────────
+
+  Consumer Verifications
 
-  payment-service v2.1.0 is COMPATIBLE with all 3 consumer(s)
+  Consumer     Version  Status      Verified At
+  ───────────  ───────  ──────────  ───────────────
+  checkout-ui  2.0.0    COMPATIBLE  2026-05-13 14:32
+  mobile-app   1.5.0    COMPATIBLE  2026-05-13 14:32
+  partner-sdk  3.2.1    COMPATIBLE  2026-05-13 14:32
 ```
 
+Blocked output:
+
 ```
-  ✖  NOT DEPLOYABLE
+  ✖  FAIL: payment-service v2.1.0 is NOT deployable in production
+  ─────────────────────────────────────────────────────
+
+  Consumer Verifications
 
-  payment-service v2.1.0 is INCOMPATIBLE with:
-    checkout-ui@2.0.0 (INCOMPATIBLE)
-    mobile-app@1.5.0  (INCOMPATIBLE)
+  Consumer     Version  Status        Verified At
+  ───────────  ───────  ────────────  ───────────────
+  checkout-ui  2.0.0    INCOMPATIBLE  2026-05-13 14:32
+  mobile-app   1.5.0    INCOMPATIBLE  2026-05-13 14:32
+
+  ➜  Run: specshield bdct verify --consumer <NAME> --provider payment-service
+  ➜  to identify and resolve incompatibilities
 ```
 
 Exit codes: `0` = deployable · `1` = blocked · `2` = error
@@ -524,12 +691,17 @@ specshield bdct matrix --org acme-store --env production
 ```
 
 ```
-  Compatibility Matrix  (env: production)
+  BDCT Compatibility Matrix
+  Environment: production
+  ─────────────────────────────────────────────────────
+
+  Consumer \ Provider  payment-service  order-service
+  ───────────────────  ───────────────  ─────────────
+  checkout-ui          COMPATIBLE       COMPATIBLE
+  mobile-app           INCOMPATIBLE     COMPATIBLE
+  partner-sdk          COMPATIBLE       UNKNOWN
 
-                    payment-service  order-service
-  checkout-ui       COMPATIBLE       COMPATIBLE
-  mobile-app        INCOMPATIBLE     COMPATIBLE
-  partner-sdk       COMPATIBLE       UNKNOWN
+  ■ COMPATIBLE  ■ INCOMPATIBLE  ■ UNKNOWN
 ```
 
 ### List Provider Specs
@@ -543,11 +715,15 @@ 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
+  Published Provider Specs
+  ─────────────────────────────────────────────────────
+  Showing 3 of 3 specs
+
+  ID    Provider         Version  Environment  Branch  Published At
+  ────  ───────────────  ───────  ───────────  ──────  ───────────────
+  1842  payment-service  v2.1.0   production   main    2026-05-13 14:30
+  1799  payment-service  v2.0.0   staging      main    2026-04-20 09:11
+  1772  order-service    v1.3.0   production   main    2026-04-28 11:02
 ```
 
 ### List Consumer Contracts
@@ -573,11 +749,14 @@ specshield bdct list \
 ```
 
 ```
-  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 Verification History
+  ─────────────────────────────────────────────────────
+  Showing 2 of 2 verifications
+
+  ID    Consumer     Provider         Cons Ver  Prov Ver  Status        Environment  Verified At
+  ────  ───────────  ───────────────  ────────  ────────  ────────────  ───────────  ───────────────
+  3081  checkout-ui  payment-service  2.0.0     v2.1.0    COMPATIBLE    production   2026-05-13 14:32
+  3082  mobile-app   payment-service  1.5.0     v2.1.0    INCOMPATIBLE  production   2026-05-13 14:32
 ```
 
 ### BDCT JSON Output
@@ -734,28 +913,60 @@ jobs:
 
 ## Config File
 
-Create `.specshield.yml` in your project root:
+Run [`specshield init`](#specshield-init--first-run-setup-wizard) to generate
+`.specshield.yml` automatically, or hand-write it. Either way, every
+`specshield ...` invocation reads the file from the project root (or any
+parent directory) and uses its values as defaults — CLI flags always win.
+
+The full schema supports both local-compare defaults and BDCT defaults:
 
 ```yaml
-failOnBreaking: true
-severity: error
+schemaVersion: 1
 
+# Local-compare defaults (used by `specshield compare`).
+failOnBreaking: true
+severity: error                  # info | warning | error
 ignore:
-  - "DELETE /admin removed"
+  - "DELETE /admin removed"      # match by substring; repeatable
 
+# Hosted compare (set --remote on the CLI to override).
 remote:
   enabled: false
-  url: "https://specshield.io/compare"
+  url: https://specshield.io/compare
   timeout: 10000
-  # apiKey: ""  ← use env var instead
-
+  # apiKey is intentionally NOT set here. Use SPECSHIELD_API_KEY in CI
+  # or `specshield login` locally. Never commit a key to a file.
+
+# BDCT defaults (used by every `specshield bdct ...` subcommand).
+bdct:
+  org: acme-pay
+  environment: staging
+  # server: https://specshield.io   # only set for self-hosted / staging
+
+  provider:
+    name: payment-service
+    spec: api/openapi.yaml          # paths are relative to this file
+    # branch: main                  # informational tag on each publish
+
+  # consumer:
+  #   name: checkout-ui
+  #   provider: payment-service
+  #   contract: contracts/payment-service.yaml
+  #   format: OPENAPI               # OPENAPI | PACT
+
+# GitHub App + bdct-action defaults.
 github:
   specPath: api/openapi.yaml
   failOnBreaking: true
   commentOnPr: true
 ```
 
-CLI flags always override config file values.
+When this file is present, BDCT commands collapse to just `--version`:
+
+```bash
+specshield bdct publish-provider --version $GITHUB_SHA
+specshield bdct can-i-deploy     --version $GITHUB_SHA
+```
 
 ---
 
@@ -788,12 +999,32 @@ specshield bdct <subcommand> [options]
 | `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 |
+| `matrix` | Compatibility matrix across all consumer/provider pairs |
 | `list-providers` | List published provider specs |
 | `list-consumers` | List published consumer contracts |
 | `list` | List verification history |
 
-All `bdct` subcommands support `--json` for machine-readable output.
+Every `bdct` subcommand accepts these flags in common:
+
+| Flag | Purpose |
+|---|---|
+| `--org <key>` | Organization key (or read from `.specshield.yml`'s `bdct.org`) |
+| `--json` | Machine-readable JSON output |
+| `--server <url>` | Override SpecShield server URL (self-hosted / staging) |
+| `--api-token <token>` | API token (overrides env / stored config) |
+
+Per-subcommand flags:
+
+| Subcommand | Flags |
+|---|---|
+| `publish-provider` | `--spec <path>`, `--provider <name>`, `--version <ver>`, `--env <env>`, `--branch <branch>` |
+| `publish-consumer` | `--contract <path>`, `--consumer <name>`, `--provider <name>`, `--version <ver>`, `--format OPENAPI\|PACT` |
+| `verify` | `--consumer <name>`, `--provider <name>`, `--consumer-version <ver>`, `--provider-version <ver>`, `--env <env>` |
+| `can-i-deploy` | `--service <name>`, `--version <ver>`, `--env <env>` |
+| `matrix` | `--env <env>` |
+| `list-providers` | `--provider <name>` (filter) |
+| `list-consumers` | `--consumer <name>` (filter), `--provider <name>` (filter) |
+| `list` | `--consumer <name>`, `--provider <name>`, `--env <env>`, `--page <n>`, `--size <n>` |
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specshield",
-  "version": "3.0.0",
-  "description": "CLI for OpenAPI breaking change detection and bi-directional contract verification — with can-i-deploy gating and GitHub PR checks.",
+  "version": "3.1.2",
+  "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/cli.js

@@ -3,6 +3,7 @@
 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 bdctCommand = require('./commands/bdct');
@@ -19,6 +20,7 @@ program
   .enablePositionalOptions();
 
 program.addCommand(compareCommand);
+program.addCommand(initCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(bdctCommand);