specshield 3.2.6 → 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

@@ -252,29 +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:** `--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.
+> **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
 
-> **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):
+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
@@ -282,7 +269,11 @@ specshield history --limit 50
 specshield history --json
 ```
 
-Expected output (once enabled):
+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
@@ -294,15 +285,13 @@ Expected output (once enabled):
 
 ## Share a Comparison
 
-> **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.
+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").
 
-Once enabled, the CLI usage will be:
+Usage:
 
 ```bash
 # Share an existing report by ID (from `specshield history`)

package/package.json

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

@@ -97,18 +97,16 @@ compare
           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.
+        // 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 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'
+            '  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'
           ));
         }
       }

package/src/commands/history.js

@@ -41,25 +41,15 @@ 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,
       });
       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 : []);
@@ -118,31 +108,4 @@ 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,14 +50,6 @@ 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' };
@@ -65,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.');
@@ -85,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();
 
@@ -126,23 +127,4 @@ 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;