specshield 3.2.5 → 3.2.6

package/README.md

@@ -5,13 +5,40 @@
 [![license](https://img.shields.io/badge/license-MIT-blue)](#license)
 [![node](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)
 
+## Contents
+
+**Get started**
+- [Quick Start](#quick-start) · [`specshield init` wizard](#specshield-init--first-run-setup-wizard) · [Login & Authentication](#login--authentication)
+
+**Why SpecShield**
+- [The Problem](#the-problem) · [The Solution](#the-solution) · [See It in Action](#see-it-in-action) · [Use Cases](#use-cases)
+- [Local vs Cloud](#local-vs-cloud) · [vs. Alternatives](#vs-alternatives) · [Pricing](#pricing)
+
+**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)
+
+**Bi-Directional Contract Testing (BDCT)**
+- [BDCT 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)
+  - [Step 1 — record a HAR](#step-1--record-a-har-file) · [Step 2 — generate contract](#step-2--turn-the-har-into-a-consumer-contract) · [Step 3 — publish + gate](#step-3--publish--gate) · [Operational concerns](#operational-concerns-read-this-before-going-live)
+- [`bdct verify-provider` — spec-vs-production conformance](#bdct-verify-provider--does-your-live-provider-actually-match-its-spec)
+
+**CI/CD**
+- [GitHub Actions workflows](#cicd--github-actions)
+
+**Reference**
+- [Config File](#config-file) · [All Options](#all-options) · [Exit Codes](#exit-codes)
+
+**Project**
+- [License](#license) · [Support](#support)
+
 ---
 
 > **OpenAPI Diff · Breaking-Change Detection · Bi-Directional Contract Testing · `can-i-deploy` Gate · Pact-File Ingest · Live-Traffic Capture · Spec-vs-Production Conformance · GitHub PR Checks**
 
 ---
 
-## Never ship a breaking change to your API consumers.
+## Never ship a breaking change to your API consumers
 
 **SpecShield** is the one CLI that does four things to keep your API safe:
 
@@ -215,7 +242,9 @@ specshield compare base.yaml target.yaml --ignore "DELETE /admin removed" --fail
 
 ## Remote Compare
 
-Sends your specs to SpecShield and stores results in your dashboard. Requires a free account.
+Sends your specs to SpecShield's hosted diff engine. Useful for keeping the
+heavy comparison off your CI runner and for cross-validating against the
+exact engine the dashboard uses. Requires a free account.
 
 ```bash
 specshield compare base.yaml target.yaml --remote
@@ -223,9 +252,29 @@ specshield compare base.yaml target.yaml --remote --fail-on-breaking
 specshield compare base.yaml target.yaml --remote --json --output result.json
 ```
 
+> **History note:** `--remote` runs the diff on our servers but currently
+> does **not** persist the result to your comparison history (saving is
+> UI-only right now — see the
+> [Comparison History](#comparison-history) section below). To save a
+> comparison, run it from the dashboard at
+> [specshield.io/account/compare](https://specshield.io/account/compare).
+> A CLI-driven save is on the roadmap.
+
 ## Comparison History
 
-Every `specshield compare --remote` is saved to your account. List recent comparisons from any machine — useful for tracking API drift over time across CI pipelines + local runs.
+> **Status: currently UI-only.** Comparison history is available in the
+> dashboard at [specshield.io/account/history](https://specshield.io/account/history).
+> The `specshield history` CLI command exists but currently exits with a
+> "use the dashboard" message — a CLI-callable API endpoint is on the
+> roadmap (the backend's `/me/*` routes require browser-session JWT auth,
+> not the CLI's API key). The dashboard shows the same data and adds
+> per-comparison drill-down.
+
+Every comparison you run **in the dashboard's `/account/compare` page** is
+saved to your account. Useful for tracking API drift over time across team
+members + machines.
+
+The CLI command (once the backend endpoint ships):
 
 ```bash
 specshield history                # last 20 comparisons
@@ -233,6 +282,8 @@ specshield history --limit 50
 specshield history --json
 ```
 
+Expected output (once enabled):
+
 ```
   Your recent comparisons
   ─────────────────────────────────────────────────────
@@ -243,7 +294,15 @@ specshield history --json
 
 ## Share a Comparison
 
-Generate a public, tokenized URL for any comparison report. Great for Slack threads, PR comments, Jira tickets.
+> **Status: currently UI-only.** Share links are generated from the
+> dashboard — open any comparison at
+> [specshield.io/account/history](https://specshield.io/account/history)
+> and click the "Share" button. Same `/r/<token>` URL shape. The
+> `specshield share` CLI command currently exits with a "use the dashboard"
+> message; CLI integration ships when the backend exposes a CLI-callable
+> share-link endpoint.
+
+Once enabled, the CLI usage will be:
 
 ```bash
 # Share an existing report by ID (from `specshield history`)
@@ -262,7 +321,8 @@ specshield share 482 --expires 30
     Expires:  2026-06-16T12:34:56Z
 ```
 
-Links use a 256-bit random token (unguessable by enumeration). Revoke any time from the dashboard.
+Links use a 256-bit random token (unguessable by enumeration). Revoke any
+time from the dashboard.
 
 ## GitHub App — PR Checks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "3.2.5",
+  "version": "3.2.6",
   "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": {

package/src/commands/compare.js

@@ -96,6 +96,21 @@ compare
           await fsExtra.outputFile(options.output, JSON.stringify(jsonOutput, null, 2));
           logger.info(`Results saved to ${options.output}`);
         }
+
+        // Honest note for --remote when the backend didn't return a history
+        // ID. The `/compare` endpoint runs the diff but does NOT persist to
+        // the user's comparison history when called with X-Api-Key auth —
+        // that's a UI-only path right now (see the share/history commands).
+        // When/if the backend starts returning historyId, this note auto-hides.
+        if ((options.remote || options.remoteUrl)
+            && !result.historyId && !result.reportId && !result.id) {
+          const chalk = require('chalk');
+          process.stdout.write('\n' + chalk.gray(
+            '  Note: --remote ran the diff on our servers but did NOT save it to your\n' +
+            '  comparison history (history save is currently UI-only). For history, run\n' +
+            '  the compare in the dashboard at https://specshield.io/account/compare.\n'
+          ));
+        }
       }
 
       // Contextual signup nudge — runs only when the user isn't logged in,

package/src/commands/history.js

@@ -49,6 +49,17 @@ history
       });
       if (spinner) spinner.stop();
 
+      // The /me/* routes currently require JWT (browser session) auth — the
+      // CLI's X-Api-Key isn't accepted, so the backend redirects to /login
+      // and axios follows the 302 to the SPA's HTML shell. Detect that and
+      // tell the user where the feature really lives, instead of silently
+      // returning an empty list.
+      if (typeof response.data === 'string'
+          && (response.data.includes('<!doctype') || response.data.includes('<html'))) {
+        printWebOnlyMessage(opts);
+        process.exit(2);
+      }
+
       const items = response.data?.content
                  || response.data?.items
                  || (Array.isArray(response.data) ? response.data : []);
@@ -107,4 +118,31 @@ function printSignupNudge() {
   console.log('');
 }
 
+/**
+ * Surfaced when the backend redirects our API-key request to /login (HTML
+ * response). The /me/compare-history endpoint is currently JWT-only — the
+ * web UI signs in via OAuth and uses a browser-session JWT. A CLI-callable
+ * API endpoint is on the roadmap; until then, the dashboard is the way.
+ */
+function printWebOnlyMessage(opts) {
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({
+      error: 'CLI_UNAVAILABLE',
+      message: 'Comparison history is currently UI-only. The CLI API endpoint is on the roadmap.',
+      dashboard: 'https://specshield.io/account/history',
+    }, null, 2) + '\n');
+    return;
+  }
+  console.log('');
+  console.log(chalk.bold('  Comparison history is currently UI-only.'));
+  console.log('');
+  console.log('  View your comparisons at:');
+  console.log('    ' + chalk.cyan('https://specshield.io/account/history'));
+  console.log('');
+  console.log(chalk.gray('  CLI access is on the roadmap — needs a backend API endpoint that'));
+  console.log(chalk.gray('  accepts the CLI\'s X-Api-Key auth (currently `/me/*` routes require'));
+  console.log(chalk.gray('  the browser-session JWT). Until then, use the dashboard.'));
+  console.log('');
+}
+
 module.exports = history;

package/src/commands/share.js

@@ -50,6 +50,14 @@ share
       process.exit(2);
     }
 
+    // The share-link endpoint lives on `/me/*` which currently requires
+    // browser-session JWT auth — the CLI's X-Api-Key gets redirected to
+    // /login. Until the backend exposes a CLI-callable endpoint, point
+    // users at the dashboard rather than letting the request fail opaquely.
+    printWebOnlyMessage();
+    process.exit(2);
+
+    // eslint-disable-next-line no-unreachable
     const spinner = ora('Generating share link...').start();
     try {
       const headers = { 'X-Api-Key': apiKey, 'X-SpecShield-Client': 'cli' };
@@ -118,4 +126,23 @@ function printSignupNudge() {
   console.log('');
 }
 
+/**
+ * Surfaced because `/me/share-links` currently requires JWT (web sign-in).
+ * The CLI X-Api-Key gets redirected to /login. Until a CLI-callable endpoint
+ * exists, the dashboard is the way.
+ */
+function printWebOnlyMessage() {
+  console.log('');
+  console.log(chalk.bold('  Share links are currently UI-only.'));
+  console.log('');
+  console.log('  Generate a share link at:');
+  console.log('    ' + chalk.cyan('https://specshield.io/account/history'));
+  console.log('  (open any comparison → click "Share").');
+  console.log('');
+  console.log(chalk.gray('  CLI access is on the roadmap — needs a backend API endpoint that'));
+  console.log(chalk.gray('  accepts the CLI\'s X-Api-Key auth (currently `/me/*` routes require'));
+  console.log(chalk.gray('  the browser-session JWT). Until then, use the dashboard.'));
+  console.log('');
+}
+
 module.exports = share;