specshield 3.0.0 → 3.1.1

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
@@ -349,6 +369,83 @@ 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
+specshield init --no-interactive \
+  --kind     provider \
+  --org      acme-pay \
+  --provider payment-service \
+  --spec     api/openapi.yaml \
+  --env      staging \
+  --write-workflow
+```
+
+### Other useful flags
+
+| 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/`. |
+
+> **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.**

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.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/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);

package/src/commands/bdct.js

@@ -7,6 +7,7 @@ const path = require('path');
 const fsExtra = require('fs-extra');
 const logger = require('../utils/logger');
 const { getStoredApiKey } = require('../config/localConfig');
+const { applyBdctDefaults } = require('../core/projectConfig');
 const {
   publishProviderSpec,
   publishConsumerContract,
@@ -31,6 +32,24 @@ function requireToken(token) {
   }
 }
 
+/**
+ * Fill missing CLI options from `.specshield.yml` if one is present, then
+ * verify every required field for `command` is set. Exits 2 with a friendly
+ * message if anything is missing.
+ */
+function withProjectDefaults(opts, command) {
+  try {
+    applyBdctDefaults(opts, command);
+  } catch (err) {
+    if (err.code === 'MISSING_REQUIRED_OPTIONS') {
+      logger.error(err.message);
+      process.exit(2);
+    }
+    throw err;
+  }
+  return opts;
+}
+
 function fmtDate(iso) {
   if (!iso) return chalk.gray('—');
   try {
@@ -99,16 +118,17 @@ function printTable(headers, rows) {
 
 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')
-  .requiredOption('--org <key>', 'Organization key')
+  .option('--spec <path>',     'Path to provider spec file (YAML or JSON)')
+  .option('--provider <name>', 'Provider service name')
+  .option('--version <ver>',   'Provider version tag')
+  .option('--org <key>',       'Organization key')
   .option('--env <environment>', 'Environment label (e.g. staging, production)')
   .option('--branch <branch>', 'Git branch name')
-  .option('--json', 'Output raw JSON')
-  .option('--server <url>', 'SpecShield server URL')
+  .option('--json',            'Output raw JSON')
+  .option('--server <url>',    'SpecShield server URL')
   .option('--api-token <token>', 'API token (overrides env / stored config)')
   .action(async (opts) => {
+    withProjectDefaults(opts, 'publish-provider');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -168,16 +188,17 @@ const publishProviderCommand = new Command('publish-provider')
 
 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')
-  .requiredOption('--org <key>', 'Organization key')
-  .option('--format <fmt>', 'Contract format: OPENAPI | PACT', 'OPENAPI')
-  .option('--json', 'Output raw JSON')
-  .option('--server <url>', 'SpecShield server URL')
+  .option('--contract <path>', 'Path to consumer contract file (OpenAPI YAML/JSON or Pact JSON)')
+  .option('--consumer <name>', 'Consumer service name')
+  .option('--provider <name>', 'Provider service name')
+  .option('--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) => {
+    withProjectDefaults(opts, 'publish-consumer');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -240,16 +261,17 @@ const publishConsumerCommand = new Command('publish-consumer')
 
 const verifyCommand = new Command('verify')
   .description('Verify consumer-provider contract compatibility')
-  .requiredOption('--consumer <name>', 'Consumer service name')
-  .requiredOption('--provider <name>', 'Provider service name')
-  .requiredOption('--consumer-version <ver>', 'Consumer version to verify')
-  .requiredOption('--provider-version <ver>', 'Provider version to verify against')
-  .requiredOption('--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')
+  .option('--consumer <name>',         'Consumer service name')
+  .option('--provider <name>',         'Provider service name')
+  .option('--consumer-version <ver>',  'Consumer version to verify')
+  .option('--provider-version <ver>',  'Provider version to verify against')
+  .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) => {
+    withProjectDefaults(opts, 'verify');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -266,14 +288,14 @@ const verifyCommand = new Command('verify')
       });
       if (spinner) spinner.stop();
 
+      const status  = String(result.status || result.result || '').toUpperCase();
+      const success = status === 'COMPATIBLE';
+
       if (opts.json) {
         process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-        return;
+        process.exit(success ? 0 : 1);
       }
 
-      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');
@@ -327,14 +349,15 @@ const verifyCommand = new Command('verify')
 
 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')
-  .requiredOption('--org <key>', 'Organization key')
+  .option('--service <name>',    'Service name (consumer or provider)')
+  .option('--version <ver>',     'Service version to check')
+  .option('--org <key>',         'Organization key')
   .option('--env <environment>', 'Target environment (e.g. qa, staging, production)')
-  .option('--json', 'Output raw JSON')
-  .option('--server <url>', 'SpecShield server URL')
+  .option('--json',              'Output raw JSON')
+  .option('--server <url>',      'SpecShield server URL')
   .option('--api-token <token>', 'API token')
   .action(async (opts) => {
+    withProjectDefaults(opts, 'can-i-deploy');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -349,14 +372,14 @@ const canIDeployCommand = new Command('can-i-deploy')
       });
       if (spinner) spinner.stop();
 
+      const deployable = result.deployable ?? result.allowed ?? false;
+      const envLabel   = opts.env ? ` in ${opts.env}` : '';
+
       if (opts.json) {
         process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-        return;
+        process.exit(deployable ? 0 : 1);
       }
 
-      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`));
@@ -400,7 +423,7 @@ const canIDeployCommand = new Command('can-i-deploy')
 
 const listCommand = new Command('list')
   .description('List BDCT verification history')
-  .requiredOption('--org <key>', 'Organization key')
+  .option('--org <key>', 'Organization key')
   .option('--consumer <name>', 'Filter by consumer service name')
   .option('--provider <name>', 'Filter by provider service name')
   .option('--env <environment>', 'Filter by environment')
@@ -410,6 +433,7 @@ const listCommand = new Command('list')
   .option('--server <url>', 'SpecShield server URL')
   .option('--api-token <token>', 'API token')
   .action(async (opts) => {
+    withProjectDefaults(opts, 'list');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -473,12 +497,13 @@ const listCommand = new Command('list')
 
 const matrixCommand = new Command('matrix')
   .description('Show ASCII compatibility matrix of consumers vs providers')
-  .requiredOption('--org <key>', 'Organization key')
+  .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) => {
+    withProjectDefaults(opts, 'matrix');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -538,12 +563,13 @@ const matrixCommand = new Command('matrix')
 
 const listProvidersCommand = new Command('list-providers')
   .description('List published provider specs')
-  .requiredOption('--org <key>', 'Organization key')
+  .option('--org <key>',       'Organization key')
   .option('--provider <name>', 'Filter by provider service name')
-  .option('--json', 'Output raw JSON')
-  .option('--server <url>', 'SpecShield server URL')
+  .option('--json',            'Output raw JSON')
+  .option('--server <url>',    'SpecShield server URL')
   .option('--api-token <token>', 'API token')
   .action(async (opts) => {
+    withProjectDefaults(opts, 'list-providers');
     const token = await resolveApiToken(opts);
     requireToken(token);
 
@@ -601,13 +627,14 @@ const listProvidersCommand = new Command('list-providers')
 
 const listConsumersCommand = new Command('list-consumers')
   .description('List published consumer contracts')
-  .requiredOption('--org <key>', 'Organization key')
+  .option('--org <key>',       'Organization key')
   .option('--consumer <name>', 'Filter by consumer service name')
   .option('--provider <name>', 'Filter by provider service name')
-  .option('--json', 'Output raw JSON')
-  .option('--server <url>', 'SpecShield server URL')
+  .option('--json',            'Output raw JSON')
+  .option('--server <url>',    'SpecShield server URL')
   .option('--api-token <token>', 'API token')
   .action(async (opts) => {
+    withProjectDefaults(opts, 'list-consumers');
     const token = await resolveApiToken(opts);
     requireToken(token);