specshield 3.3.5 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # SpecShield CLI changelog
 
+## 3.4.0 — 2026-07-29 — `govern` command (API governance in the CLI)
+
+### Added
+
+- **`specshield govern <spec>` — API governance & linting from the CLI.** Scores an
+  OpenAPI spec against SpecShield's governance rules (OWASP + design) via the hosted
+  gate (`POST /api/governance/gate`) and prints findings (grouped by severity, with
+  rule id + location), a compliance score + A–F grade, and a PASS/FAIL verdict.
+  Exit codes match the other gates: `0` pass · `1` fail · `2` error.
+  - Flags: `--ruleset <path>` (lint against a Spectral-format ruleset file),
+    `--min-score <n>`, `--fail-on-warning`, `--no-fail-on-error`, `--org <key>`
+    (apply the org's active waivers), `--advisory` (report but never fail CI),
+    `--json`, `--output <file>`, `--api-token`, `--server`.
+  - Team plan and above (needs an API key); free/unauthed callers get a friendly
+    "requires a paid plan" message and exit `2`.
+- README: new **Governance** section + command reference; the "API governance"
+  use case now points at `specshield govern` instead of "not a CLI command yet".
+
+## 3.3.6 — 2026-07-28 — Docs & platform positioning
+
+Documentation-only release — **no CLI behavior change**; existing CI keeps working.
+
+### Changed
+
+- **README reframed around the SpecShield™ platform.** New "One platform, five ways
+  to run it" section covering the GitHub App, GitHub Action, this CLI, the
+  IntelliJ/JetBrains plugin, and the MCP server — plus the hosted dashboard.
+- **API governance surfaced as a first-class capability** (OWASP + design-rule
+  linting, standard rule packs, waivers, SARIF/JUnit/HTML reports) — available via
+  the IntelliJ plugin, GitHub Action, MCP server, and dashboard.
+- Corrected the "API governance" use case that previously described drift-tracking;
+  split into "API drift tracking" and proper "API governance & linting".
+- Noted that Optic was archived (Jan 2026) and linked the full comparison at
+  `specshield.io/alternatives`.
+- Applied the ™ mark to the SpecShield brand where appropriate.
+
 ## 3.3.0 — 2026-06-20 — Complex-spec hardening + "contract compatibility testing"
 
 A minor release focused on the local diff engine's accuracy on advanced OpenAPI

package/README.md

@@ -1,4 +1,4 @@
-# SpecShield CLI
+# SpecShield™ CLI
 
 [![npm](https://img.shields.io/npm/v/specshield)](https://www.npmjs.com/package/specshield)
 [![downloads](https://img.shields.io/npm/dt/specshield)](https://www.npmjs.com/package/specshield)
@@ -17,6 +17,9 @@
 **Commands — local & hosted compare**
 - [Local Compare](#local-compare) · [Remote Compare](#remote-compare) · [Comparison History](#comparison-history) · [Share a Comparison](#share-a-comparison) · [GitHub App PR Checks](#github-app--pr-checks)
 
+**Governance — lint & gate**
+- [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr)
+
 **Contract Compatibility Testing — the `bdct` commands**
 - [Overview & full command reference](#bi-directional-contract-testing-bdct)
 - [`bdct capture from-har` — HAR → consumer contract](#bdct-capture-from-har--turn-real-traffic-into-a-consumer-contract)
@@ -34,28 +37,47 @@
 
 ---
 
-> **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
+> **Contract Compatibility Testing · OpenAPI Diff · Breaking-Change Detection · `can-i-deploy` Deploy Gate · API Governance & Linting · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
 
 ---
 
 ## Never ship a breaking change to your API consumers
 
-**SpecShield is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
+**SpecShield™ is contract compatibility testing for APIs** — catch breaking changes before they reach your consumers, and gate every deploy with `can-i-deploy`. *(Contract compatibility testing is also known as bidirectional contract testing.)*
 
-It's the one CLI that does four things to keep your API safe:
+It's the one CLI that does five things to keep your API safe:
 
 1. **Diff** two OpenAPI specs and fail CI on breaking changes.
 2. **Contract compatibility testing** with `can-i-deploy` — block a deploy that would break a consumer.
-3. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
-4. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
+3. **`govern`** — lint your spec against OWASP + design rules and gate the PR on violations.
+4. **`bdct capture from-har`** — turn recorded traffic into an accurate consumer contract (no Pact DSL).
+5. **`bdct verify-provider`** — prove the running provider actually matches its OpenAPI spec.
 
 ```
-OpenAPI diff  +  contract compatibility checks  +  HAR → consumer contract  +  spec-vs-production conformance  —  in one CLI.
+OpenAPI diff  +  contract compatibility checks  +  API governance  +  HAR → consumer contract  +  spec-vs-production conformance  —  in one CLI.
 ```
 
 No broker. No Pact DSL. Language-agnostic. Works in 30 seconds. Local mode never uploads your specs.
 
-> 🤖 **Using an AI coding agent?** The [SpecShield MCP server](https://github.com/specshield26/specshield-mcp-server) brings the same `can-i-deploy` deploy gate into Claude, Cursor, and other MCP clients — ask *"is it safe to ship this API change to my consumers?"* right inside your agent. Same job, two entry points: this CLI for CI/CD, the MCP server for agents.
+---
+
+## One platform, five ways to run it
+
+This CLI is one surface of the **SpecShield™ platform**. The same contract-compatibility and governance engine powers every entry point — they share one project file (`.specshield.yml`), one API key, and one set of audit events. Adopt the one that fits your stack today and grow into the others:
+
+| Surface | Best for |
+|---|---|
+| **GitHub App** — [github.com/apps/specshield](https://github.com/apps/specshield) | Zero-config PR checks. Install once; every PR gets a check run and a diff comment. |
+| **GitHub Action** — [`specshield26/bdct-action@v1`](https://github.com/marketplace/actions/specshield-bdct) | Pinned, reproducible BDCT + governance gate in any GitHub workflow. |
+| **CLI** *(this package)* | Any CI — GitLab, Jenkins, CircleCI, Bitbucket, Drone — or your laptop. |
+| **IntelliJ plugin** — [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/33137-specshield) | Inline spec findings, one-click auto-fixes, compare & explain — inside IntelliJ IDEA, WebStorm, PyCharm and more. |
+| **MCP server** — [`specshield-mcp-server`](https://github.com/specshield26/specshield-mcp-server) | Give Claude, Cursor, and other AI agents the same deploy gate. |
+
+Plus a hosted **dashboard** at [specshield.io](https://specshield.io) — compatibility matrix, consumer registry, append-only audit log, and **API governance** scorecards (OWASP + design-rule linting, standard rule packs, waivers, SARIF/JUnit/HTML reports).
+
+> 🤖 **AI agents:** the MCP server answers *"is it safe to ship this API change to my consumers?"* right inside your agent — analyze-only, it never touches your code. Same job, two entry points: this CLI for CI/CD, the MCP server for agents.
+
+> See how the platform stacks up against Pactflow, Pact, Optic, oasdiff, Bump.sh, Stoplight, and API gateways (Apigee, Azure API Management) at **[specshield.io/alternatives](https://specshield.io/alternatives)**.
 
 ---
 
@@ -191,9 +213,10 @@ specshield bdct can-i-deploy     --version $GITHUB_SHA
 - **Pull-request validation** — catch breaking changes before merge with `specshield compare`.
 - **CI/CD gating** — exit code `1` stops the pipeline automatically.
 - **Microservices contract safety** — consumers publish what they expect, providers verify they deliver it, no cross-team surprises.
-- **API governance** — track API drift over time across your platform; know what changed, when, by whom.
-- **Provider conformance** *(new)* — make sure your *running* service actually matches its published OpenAPI spec, not just on paper.
-- **Pact-free consumer contracts** *(new)* — record real traffic with `capture from-har` and get an OpenAPI consumer contract without writing a single line of Pact DSL.
+- **API drift tracking** — track how your specs change over time across the platform; know what changed, when, and by whom.
+- **API governance & linting** — score every spec against OWASP + design rules, bring your own Spectral ruleset, and gate PRs on violations with [`specshield govern`](#governance--lint-a-spec-and-gate-the-pr). The same engine also powers the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/33137-specshield), the [GitHub Action](https://github.com/marketplace/actions/specshield-bdct), the [MCP server](https://github.com/specshield26/specshield-mcp-server), and the [dashboard](https://specshield.io).
+- **Provider conformance** — make sure your *running* service actually matches its published OpenAPI spec, not just on paper.
+- **Pact-free consumer contracts** — record real traffic with `capture from-har` and get an OpenAPI consumer contract without writing a single line of Pact DSL.
 
 ---
 
@@ -338,6 +361,68 @@ github:
 
 ---
 
+## Governance — lint a spec and gate the PR
+
+**Static API governance: score your OpenAPI spec against OWASP + design rules and fail CI on violations.** *(Team plan and above — runs on SpecShield's hosted engine, so it needs an API key.)*
+
+```bash
+# Lint against SpecShield's built-in governance rules
+specshield govern api/openapi.yaml
+
+# Lint against a Spectral-format ruleset (OWASP pack, your house style, …)
+specshield govern api/openapi.yaml --ruleset .specshield/ruleset.yaml
+
+# Gate CI: require a minimum score, and fail on warnings too
+specshield govern api/openapi.yaml --min-score 80 --fail-on-warning
+
+# Report only — print findings but never fail the build
+specshield govern api/openapi.yaml --advisory
+```
+
+Sample output:
+
+```
+  SpecShield™ Governance Report
+  ─────────────────────────────────────────
+  error    security-scheme-missing  $.paths./payments.post
+           operation has no security scheme
+           fix: add a security requirement
+  info     operation-operation-id   $.paths./health.get
+           operation is missing an operationId
+  ─────────────────────────────────────────
+  Score 74/100 · grade C  ·  1 error · 0 warning · 1 info
+
+  ✖ FAIL — governance policy not met:
+    • 1 error-severity finding
+```
+
+Exit codes: `0` = passed the gate · `1` = failed the gate · `2` = error (invalid spec, missing token, or paid-plan required).
+
+| Flag | Purpose | Default |
+|---|---|---|
+| `--ruleset <path>` | Lint against a Spectral-format ruleset file (uses the ruleset engine). | built-in rules |
+| `--min-score <n>` | Minimum compliance score (0–100) required to pass. | `70` |
+| `--fail-on-warning` | Fail the gate when any warning-severity finding is present. | off |
+| `--no-fail-on-error` | Do **not** fail the gate on error-severity findings. | fails on error |
+| `--org <key>` | Apply your org's active governance waivers to the verdict. | none |
+| `--advisory` | Report findings but always exit `0` (never fail CI). | off |
+| `--json` | Machine-readable JSON output (the full gate response). | off |
+| `--output <file>` | Also save the JSON result to a file. | — |
+| `--api-token <token>` | API token (else `SPECSHIELD_API_KEY` / stored config). | — |
+| `--server <url>` | Override the SpecShield server URL (self-hosted / staging). | `https://specshield.io` |
+
+Run it in CI right after your build:
+
+```yaml
+- name: Govern the API spec
+  env: { SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }} }
+  run: specshield govern api/openapi.yaml --min-score 80
+```
+
+> The same governance engine powers the [IntelliJ plugin](https://plugins.jetbrains.com/plugin/33137-specshield), the [GitHub Action](https://github.com/marketplace/actions/specshield-bdct), the [MCP server](https://github.com/specshield26/specshield-mcp-server), and the [dashboard](https://specshield.io) — with catalog scorecards, waivers, and SARIF/JUnit/HTML reports.
+
+---
+
 # Bi-Directional Contract Testing (BDCT)
 
 **Compatibility without Pact's broker overhead or DSL.**
@@ -1093,6 +1178,8 @@ jobs:
 | CLI-first | ✅ | ❌ | ✅ | partial |
 | Free tier | ✅ | ❌ | ✅ (OSS) | ✅ (OSS) |
 
+> **Note:** Optic — a popular OpenAPI-diff tool — was **archived in January 2026** and is no longer maintained; SpecShield is a drop-in replacement for its diff and CI checks. For the full, up-to-date comparison (including Bump.sh, Stoplight, and API gateways like Apigee and Azure API Management), see **[specshield.io/alternatives](https://specshield.io/alternatives)**.
+
 ---
 
 ## Pricing
@@ -1326,6 +1413,23 @@ specshield share <reportId | base.yaml target.yaml> [options]
 | `--expires <days>` | Make the link expire after N days (default: never) |
 | `--api-key <key>` | Override stored API key |
 
+```bash
+specshield govern <spec> [options]
+```
+
+| Option | Description |
+|---|---|
+| `--ruleset <path>` | Lint against a Spectral-format ruleset file |
+| `--min-score <n>` | Minimum compliance score (0–100) to pass (default 70) |
+| `--fail-on-warning` | Fail the gate on any warning-severity finding |
+| `--no-fail-on-error` | Do not fail the gate on error-severity findings |
+| `--org <key>` | Apply the org's active governance waivers |
+| `--advisory` | Report findings but always exit 0 |
+| `--json` | Machine-readable JSON output |
+| `--output <file>` | Save the JSON result to a file |
+| `--api-token <token>` | API token (overrides env / stored config) |
+| `--server <url>` | Override SpecShield server URL |
+
 ```bash
 specshield bdct <subcommand> [options]
 ```
@@ -1395,7 +1499,9 @@ MIT © SpecShield Software Private Limited
 
 <div align="center">
 
-**[⭐ Star on GitHub](https://github.com/specshield26/specshield-cli) · [📦 View on npm](https://www.npmjs.com/package/specshield) · [🚀 Create free account](https://specshield.io)**
+**The SpecShield™ platform:** [Dashboard](https://specshield.io) · [GitHub App](https://github.com/apps/specshield) · [GitHub Action](https://github.com/marketplace/actions/specshield-bdct) · [IntelliJ Plugin](https://plugins.jetbrains.com/plugin/33137-specshield) · [MCP Server](https://github.com/specshield26/specshield-mcp-server)
+
+**[⭐ Star on GitHub](https://github.com/specshield26/specshield-cli) · [📦 View on npm](https://www.npmjs.com/package/specshield) · [🚀 Create free account](https://specshield.io) · [⚖️ Compare](https://specshield.io/alternatives)**
 
 *Stop finding out about API breakage from your users.*
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.3.5",
+  "version": "3.4.0",
   "description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
   "main": "src/cli.js",
   "bin": {

package/src/api/bdctClient.js

@@ -108,6 +108,19 @@ async function listConsumerContracts(server, apiToken, { org, consumer, provider
   } catch (err) { throw apiError(err); }
 }
 
+/**
+ * Run the governance deploy gate on a spec. Always returns HTTP 200 with a
+ * pass/fail verdict in the body (a failed gate is a valid result, not an error),
+ * so only real failures (400 invalid spec, 402 paid-plan, 403 org, 503 disabled,
+ * network) throw. `payload` = { spec, ruleset?, policy?, orgKey? }.
+ */
+async function governanceGate(server, apiToken, payload) {
+  try {
+    const res = await buildClient(server, apiToken).post('/api/governance/gate', payload);
+    return res.data;
+  } catch (err) { throw apiError(err); }
+}
+
 module.exports = {
   publishProviderSpec,
   publishConsumerContract,
@@ -117,4 +130,5 @@ module.exports = {
   getMatrix,
   listProviderSpecs,
   listConsumerContracts,
+  governanceGate,
 };

package/src/cli.js

@@ -7,6 +7,7 @@ const initCommand = require('./commands/init');
 const loginCommand = require('./commands/login');
 const logoutCommand = require('./commands/logout');
 const bdctCommand = require('./commands/bdct');
+const governCommand = require('./commands/govern');
 const historyCommand = require('./commands/history');
 const shareCommand = require('./commands/share');
 const whoamiCommand = require('./commands/whoami');
@@ -27,6 +28,7 @@ program.addCommand(initCommand);
 program.addCommand(loginCommand);
 program.addCommand(logoutCommand);
 program.addCommand(bdctCommand);
+program.addCommand(governCommand);
 program.addCommand(historyCommand);
 program.addCommand(shareCommand);
 program.addCommand(whoamiCommand);

package/src/commands/govern.js

@@ -0,0 +1,142 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const fsExtra = require('fs-extra');
+const logger = require('../utils/logger');
+const { loadSpec } = require('../core/loadSpec');
+const { getStoredApiKey } = require('../config/localConfig');
+const { governanceGate } = require('../api/bdctClient');
+
+// Token precedence mirrors the bdct subcommands.
+async function resolveApiToken(opts) {
+  return opts.apiToken || process.env.SPECSHIELD_API_KEY || (await getStoredApiKey()) || null;
+}
+
+const SEV_ORDER = { error: 0, warning: 1, info: 2 };
+
+function sevLabel(sev) {
+  const s = String(sev || '').toLowerCase();
+  if (s === 'error')   return chalk.red('error  ');
+  if (s === 'warning') return chalk.yellow('warning');
+  return chalk.blue('info   ');
+}
+
+function gradeColor(grade) {
+  const g = String(grade || '—').toUpperCase();
+  if (g === 'A' || g === 'B') return chalk.green(g);
+  if (g === 'C')              return chalk.yellow(g);
+  return chalk.red(g);
+}
+
+const govern = new Command('govern')
+  .description('Lint an OpenAPI spec against governance rules (OWASP + design) and gate the PR')
+  .argument('<spec>', 'Path to the OpenAPI spec to govern (YAML or JSON)')
+  .option('--ruleset <path>', 'Lint against a Spectral-format ruleset file (uses the ruleset engine)')
+  .option('--min-score <n>', 'Minimum compliance score (0–100) required to pass (default 70)', (v) => parseInt(v, 10))
+  .option('--fail-on-warning', 'Fail the gate when any warning-severity finding is present')
+  .option('--no-fail-on-error', 'Do NOT fail the gate on error-severity findings')
+  .option('--org <key>', 'Org key — applies your org’s active governance waivers to the verdict')
+  .option('--advisory', 'Report findings but always exit 0 (never fail CI)')
+  .option('--json', 'Output machine-readable JSON')
+  .option('--output <file>', 'Also save the JSON result to this file')
+  .option('--server <url>', 'SpecShield server URL')
+  .option('--api-token <token>', 'API token (overrides env / stored config)')
+  .action(async (specPath, opts) => {
+    try {
+      const token = await resolveApiToken(opts);
+      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);
+      }
+
+      const spinner = opts.json ? null : ora('Loading spec...').start();
+      const specText = await loadSpec(specPath);
+      const ruleset = opts.ruleset ? await loadSpec(opts.ruleset) : null;
+
+      // Only send policy fields the user overrode; the server applies documented
+      // defaults (minScore 70, failOnError true, failOnWarning false) otherwise.
+      const policy = {};
+      if (opts.minScore !== undefined && !Number.isNaN(opts.minScore)) policy.minScore = opts.minScore;
+      if (opts.failOnWarning) policy.failOnWarning = true;
+      if (opts.failOnError === false) policy.failOnError = false; // set by --no-fail-on-error
+
+      if (spinner) spinner.text = 'Running governance review...';
+      const resp = await governanceGate(opts.server, token, {
+        spec: specText,
+        ruleset,
+        policy: Object.keys(policy).length ? policy : null,
+        orgKey: opts.org || null,
+      });
+      if (spinner) spinner.stop();
+
+      if (opts.json) {
+        const out = JSON.stringify(resp, null, 2);
+        process.stdout.write(out + '\n');
+        if (opts.output) await fsExtra.outputFile(opts.output, out);
+      } else {
+        renderHuman(resp);
+        if (opts.output) await fsExtra.outputFile(opts.output, JSON.stringify(resp, null, 2));
+      }
+
+      if (opts.advisory) process.exit(0);
+      process.exit(resp.passed ? 0 : 1);
+    } catch (err) {
+      if (err.status === 402) {
+        logger.error('API governance requires a paid plan (Team or above). See https://specshield.io/pricing');
+        process.exit(2);
+      }
+      if (err.status === 503) {
+        logger.error('Governance is not enabled on this SpecShield server.');
+        process.exit(2);
+      }
+      logger.error(`Error: ${err.message}`);
+      process.exit(2);
+    }
+  });
+
+function renderHuman(resp) {
+  const review = resp.review || {};
+  const findings = Array.isArray(review.findings) ? review.findings.slice() : [];
+  const score = review.score || {};
+
+  process.stdout.write('\n  ' + chalk.bold('SpecShield™ Governance Report') + '\n');
+  process.stdout.write('  ' + chalk.gray('─────────────────────────────────────────') + '\n');
+
+  if (findings.length === 0) {
+    process.stdout.write('  ' + chalk.green('✔ No governance findings.') + '\n');
+  } else {
+    findings.sort((a, b) =>
+      (SEV_ORDER[String(a.severity).toLowerCase()] ?? 3) - (SEV_ORDER[String(b.severity).toLowerCase()] ?? 3));
+    for (const f of findings) {
+      const loc = f.location ? chalk.gray('  ' + f.location) : '';
+      process.stdout.write(`  ${sevLabel(f.severity)}  ${chalk.cyan(f.ruleId || '')}${loc}\n`);
+      if (f.message) process.stdout.write(`           ${f.message}\n`);
+      if (f.suggestedFix) process.stdout.write(`           ${chalk.gray('fix: ' + f.suggestedFix)}\n`);
+    }
+  }
+
+  process.stdout.write('  ' + chalk.gray('─────────────────────────────────────────') + '\n');
+  const scoreVal = (score.value === undefined || score.value === null) ? '—' : score.value;
+  process.stdout.write(
+    `  Score ${chalk.bold(scoreVal)}/100 · grade ${gradeColor(score.grade)}  ·  `
+    + `${chalk.red((review.errorCount || 0) + ' error')} · `
+    + `${chalk.yellow((review.warningCount || 0) + ' warning')} · `
+    + `${chalk.blue((review.infoCount || 0) + ' info')}`
+    + (resp.waivedCount ? `  ·  ${chalk.gray(resp.waivedCount + ' waived')}` : '')
+    + '\n'
+  );
+
+  if (resp.passed) {
+    process.stdout.write('\n  ' + chalk.green.bold('✔ PASS')
+      + chalk.gray(` — meets the governance policy (min score ${resp.scoreThreshold}).`) + '\n\n');
+  } else {
+    process.stdout.write('\n  ' + chalk.red.bold('✖ FAIL') + chalk.gray(' — governance policy not met:') + '\n');
+    for (const r of (resp.reasons || [])) process.stdout.write('    ' + chalk.red('•') + ' ' + r + '\n');
+    if (resp.recommendedAction) process.stdout.write('\n  ' + chalk.gray(resp.recommendedAction) + '\n');
+    process.stdout.write('\n');
+  }
+}
+
+module.exports = govern;