specshield 3.2.5 → 3.2.7

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # SpecShield CLI changelog
 
+## 3.2.7 — 2026-06-12 — `history` + `share` now work from the CLI
+
+`specshield history` and `specshield share` were previously "UI-only" stubs —
+the backend's comparison-history and share-link endpoints lived on JWT-only
+routes that rejected the CLI's API key. The backend now exposes API-key-callable
+endpoints (`/api/compare-history`, `/api/share-links`) and `/compare` returns the
+saved comparison's id, so the full CLI/CI flow works end to end.
+
+### Added
+
+- **`specshield history`** lists your recent comparisons (id, breaking count,
+  date, `base → target`). Honors `--limit` and `--json`. Reads the new
+  `/api/compare-history` endpoint.
+- **`specshield share <id>`** generates a public `/r/<token>` link for a saved
+  comparison via the new `/api/share-links` endpoint. `--expires <days>` sets an
+  expiry. `specshield share <base> <target>` still compares-and-shares in one step.
+- **`compare --remote` now returns a `historyId`** when run with an API key —
+  feed it straight into `specshield share` (the CI "compare → share link in PR
+  comment" flow).
+
+### Changed
+
+- `compare --remote`'s footer is accurate again: with an API key the comparison
+  is saved (no note); without one it notes the diff ran but wasn't saved.
+- Removed the "currently UI-only" notices from `history` / `share` (and the
+  matching README callouts) now that both work.
+
+### Fixed
+
+- `specshield share` validates the report id is a positive number and gives a
+  clear message (pointing at `specshield history`) instead of a server 400.
+
 ## 3.2.3 — 2026-05-28 — BDCT fidelity: HAR capture + provider conformance
 
 Two new `bdct` sub-commands that close the contract-fidelity gap PactFlow

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,16 @@ specshield compare base.yaml target.yaml --remote --fail-on-breaking
 specshield compare base.yaml target.yaml --remote --json --output result.json
 ```
 
+> **History note:** with an API key set (run `specshield login`, or pass
+> `--api-key` / `SPECSHIELD_API_KEY`), `--remote` saves each comparison to
+> your history and the response includes a `historyId` you can hand to
+> `specshield share`. Without a key the diff still runs — it just isn't saved.
+
 ## 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.
+Every comparison you run with `--remote` (and every one from the dashboard) is
+saved to your account — useful for tracking API drift over time across team
+members and machines. List them straight from the CLI:
 
 ```bash
 specshield history                # last 20 comparisons
@@ -233,6 +269,12 @@ specshield history --limit 50
 specshield history --json
 ```
 
+The dashboard at
+[specshield.io/account/history](https://specshield.io/account/history) shows
+the same data with per-comparison drill-down.
+
+Example output:
+
 ```
   Your recent comparisons
   ─────────────────────────────────────────────────────
@@ -243,7 +285,13 @@ specshield history --json
 
 ## Share a Comparison
 
-Generate a public, tokenized URL for any comparison report. Great for Slack threads, PR comments, Jira tickets.
+Generate a public `/r/<token>` link for any comparison — paste it into Slack, a
+GitHub PR comment, or a Jira ticket and anyone can view the diff without a
+SpecShield account. You can also create links from the dashboard (open a
+comparison at [specshield.io/account/history](https://specshield.io/account/history)
+→ "Share").
+
+Usage:
 
 ```bash
 # Share an existing report by ID (from `specshield history`)
@@ -262,7 +310,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.7",
   "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,19 @@ compare
           await fsExtra.outputFile(options.output, JSON.stringify(jsonOutput, null, 2));
           logger.info(`Results saved to ${options.output}`);
         }
+
+        // Note for an anonymous --remote: the diff ran but wasn't saved
+        // because no API key was sent. An authenticated --remote persists the
+        // comparison and the backend returns a historyId, so this note 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 but did NOT save it to your history\n' +
+            '  (no API key). Run "specshield login" (or set SPECSHIELD_API_KEY) to\n' +
+            '  save comparisons and unlock "specshield history" / "specshield share".\n'
+          ));
+        }
       }
 
       // Contextual signup nudge — runs only when the user isn't logged in,

package/src/commands/history.js

@@ -41,8 +41,9 @@ history
     const spinner = opts.json ? null : ora('Fetching your comparison history...').start();
     try {
       const size = parseInt(opts.limit, 10) || 20;
-      const response = await axios.get(`${opts.apiUrl}/me/compare-history`, {
-        // Backend uses Spring Data Page conventions: page (0-indexed) + size.
+      const response = await axios.get(`${opts.apiUrl}/api/compare-history`, {
+        // Backend paginates with page (0-indexed) + size; the /api endpoint
+        // returns a PagedResponse envelope ({ content, page, size, ... }).
         params: { page: 0, size },
         headers: { 'X-Api-Key': apiKey, 'X-SpecShield-Client': 'cli' },
         timeout: 10000,

package/src/commands/share.js

@@ -57,17 +57,17 @@ share
 
       let reportId;
       if (target) {
-        // Inline-compare path: run a /compare with --remote semantics to
-        // persist the result, then immediately share the resulting history
-        // row. Two API calls but keeps the backend share endpoint single-purpose.
+        // Inline-compare path: run a /compare (which persists when called with
+        // a valid X-Api-Key), then immediately share the resulting history row.
+        // Two API calls but keeps the backend share endpoint single-purpose.
         spinner.text = 'Running remote comparison...';
         const baseSpec   = await loadSpec(reportOrBase);
         const targetSpec = await loadSpec(target);
         const compareResp = await axios.post(`${opts.apiUrl}/compare`,
           { baseSpec, targetSpec },
           { headers, timeout: 30000 });
-        // The /compare endpoint returns the diff; the persisted history ID is
-        // on the response (added by CompareHistoryService).
+        // The /compare endpoint returns the diff plus the persisted row's
+        // historyId (present because we authenticated with X-Api-Key).
         reportId = compareResp.data?.historyId || compareResp.data?.reportId;
         if (!reportId) {
           throw new Error('Comparison succeeded but no history ID was returned — cannot create share link.');
@@ -77,8 +77,17 @@ share
         reportId = reportOrBase;
       }
 
-      const response = await axios.post(`${opts.apiUrl}/me/share-links`,
-        { reportId, expiresInDays },
+      // The backend's reportId is a numeric history id. Validate before the
+      // call so a typo gets a clear message instead of a 400 from the server.
+      const numericReportId = Number(reportId);
+      if (!Number.isInteger(numericReportId) || numericReportId <= 0) {
+        spinner.stop();
+        logger.error(`Invalid report ID "${reportId}". Expected a numeric comparison ID — see "specshield history".`);
+        process.exit(2);
+      }
+
+      const response = await axios.post(`${opts.apiUrl}/api/share-links`,
+        { reportId: numericReportId, expiresInDays },
         { headers, timeout: 15000 });
       spinner.stop();