specshield 1.0.4 → 1.0.6

package/README.md

@@ -1,153 +1,259 @@
-# 🚀 SpecShield — OpenAPI Diff & Breaking Change Detection CLI
+# SpecShield CLI
 
-![npm](https://img.shields.io/npm/v/specshield)
-![downloads](https://img.shields.io/npm/dw/specshield)
-![license](https://img.shields.io/badge/license-MIT-blue)
-![node](https://img.shields.io/badge/node-%3E%3D18-green)
+[![npm](https://img.shields.io/npm/v/specshield)](https://www.npmjs.com/package/specshield)
+[![downloads](https://img.shields.io/npm/dw/specshield)](https://www.npmjs.com/package/specshield)
+[![license](https://img.shields.io/badge/license-MIT-blue)](#license)
+[![node](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
 
 Compare OpenAPI and Swagger specs, detect breaking changes, and fail CI before incompatible API changes reach production.
 
+---
 
-## 📌 What is SpecShield?
-
-SpecShield is a CLI tool that compares two OpenAPI/Swagger specifications and detects:
-
-- ❌ Breaking changes
-- ➕ Additions
-- 🔄 Modifications
+## Table of Contents
 
-It is designed for:
-- CI/CD pipelines
-- Backend developers
-- API governance teams
-- Local development workflows
+- [What is SpecShield CLI?](#what-is-specshield-cli)
+- [Installation](#installation)
+- [Local Compare](#local-compare)
+- [Authentication](#authentication)
+- [Generate an API Token](#generate-an-api-token)
+- [Remote Compare](#remote-compare)
+- [Config File](#config-file)
+- [All Options](#all-options)
+- [Exit Codes](#exit-codes)
+- [CI/CD — GitHub Actions](#cicd--github-actions)
+- [Support](#support)
 
 ---
 
-## ❗ Why SpecShield?
+## What is SpecShield CLI?
 
-API changes can silently break:
-- Mobile apps
-- Frontend clients
-- Partner integrations
-- Internal microservices
+SpecShield CLI is a command-line tool for comparing two OpenAPI/Swagger specifications and detecting what changed between them. It classifies changes into:
 
-Manual API review is:
-- ❌ Error-prone
-- ❌ Time-consuming
-- ❌ Not scalable
+- **Breaking changes** — removed endpoints, changed required fields, incompatible type changes
+- **Modifications** — changed behavior that may or may not break clients
+- **Additions** — new endpoints or fields
+- **Warnings** — low-severity notices
 
-👉 SpecShield solves this by automating API contract validation.
+It works in two modes:
 
----
-
-## 🎯 Key Benefits
-
-- 🚫 Prevent breaking API releases
-- ⚙️ Enforce API contract checks in CI/CD
-- 🔍 Compare OpenAPI specs automatically
-- 📊 Generate machine-readable reports
-- 🧩 Integrate easily with existing workflows
-- 🛑 Fail builds when breaking changes are detected
+| Mode | Description |
+|---|---|
+| **Local** | Compares two spec files on your machine. No account needed. |
+| **Remote** | Sends specs to the SpecShield hosted API. Requires an API token. Results are stored in your dashboard. |
 
 ---
 
-## ✨ Features
-
-- Detect breaking changes, additions, and modifications
-- Support YAML and JSON OpenAPI specs
-- CI/CD-ready with exit codes
-- JSON output for automation
-- `.specshield.yml` config support
-- Ignore list for known changes
-- Future SaaS-ready remote mode
-
 ## Installation
 
 ```bash
 npm install -g specshield
-# or use locally:
-npm install && npm link
 ```
 
-## Usage
+Verify the installation:
+
+```bash
+specshield --version
+```
+
+---
+
+## Local Compare
+
+No account or token required for local comparisons.
 
-### Basic comparison
 ```bash
 specshield compare base.yaml target.yaml
 ```
 
-### Fail CI on breaking changes
+Fail CI if breaking changes are found:
+
 ```bash
 specshield compare base.yaml target.yaml --fail-on-breaking
 ```
 
-### JSON output (for scripts/automation)
+Output as JSON:
+
 ```bash
 specshield compare base.yaml target.yaml --json
 ```
 
-### Save results to file
+Save results to a file:
+
 ```bash
 specshield compare base.yaml target.yaml --output result.json
 ```
 
-### Ignore specific changes
+Ignore specific changes:
+
 ```bash
 specshield compare base.yaml target.yaml --ignore "DELETE /users removed" --fail-on-breaking
 ```
 
-### Use custom config
+---
+
+## Authentication
+
+Remote compare requires a SpecShield account and an API token.
+
+### Sign in to SpecShield
+
+1. Go to [https://specshield.io](https://specshield.io)
+2. Sign in with your email/password, GitHub, or Google account
+3. You will land on your account dashboard
+
+### Generate an API Token
+
+1. From your dashboard, go to **Account → API Keys**
+   (direct link: [https://specshield.io/account/keys](https://specshield.io/account/keys))
+2. Click **Generate API Key**
+3. Copy the token — it starts with `ss_` and is shown only once
+4. Store it securely (password manager, secrets vault, or CI/CD secret)
+
+### Configure the CLI
+
+Run the login command with your token:
+
 ```bash
-specshield compare base.yaml target.yaml --config ./configs/.specshield.yml
+specshield login --api-key ss_your_token_here
 ```
 
-## Options
+This validates the token against the SpecShield API and saves it to `~/.specshield/config.json`. You will not need to pass the token on every command after this.
 
-| Option | Description |
-|---|---|
-| `--json` | Output machine-readable JSON |
-| `--output <file>` | Save result to file |
-| `--fail-on-breaking` | Exit 1 if breaking changes found |
-| `--allow-breaking` | Override fail behavior |
-| `--config <path>` | Path to `.specshield.yml` |
-| `--ignore <change>` | Ignore a change string (repeatable) |
-| `--severity <level>` | `info` / `warning` / `error` |
-| `--remote-url <url>` | Remote API endpoint (future mode) |
-| `--timeout <ms>` | Timeout for remote requests |
+**Example output:**
+
+```
+✔ Logged in successfully.
+
+  Customer:  Jane Smith
+  Plan:      FREE
+  Config:    /Users/jane/.specshield/config.json
+
+  Run: specshield compare base.yaml target.yaml --remote
+```
+
+### Alternative: Environment Variable
+
+If you prefer not to use the stored config (e.g. in CI/CD), set the token as an environment variable:
+
+```bash
+export SPECSHIELD_API_KEY=ss_your_token_here
+specshield compare base.yaml target.yaml --remote
+```
+
+The token resolution order is:
+
+1. `--api-key` flag (highest priority)
+2. `SPECSHIELD_API_KEY` environment variable
+3. Stored config (`~/.specshield/config.json`)
+4. `remote.apiKey` in `.specshield.yml`
+
+### Log Out
+
+To remove the stored token:
+
+```bash
+specshield logout
+```
+
+---
+
+## Remote Compare
+
+Remote compare sends your spec files to the SpecShield hosted API at [https://specshield.io](https://specshield.io). Results are processed server-side and stored in your dashboard for review.
+
+**When to use remote mode:**
+- You want comparison history tracked in the SpecShield dashboard
+- Your team shares a centralized view of API drift over time
+- You are on a plan with advanced reporting features
+
+### Basic remote compare
+
+```bash
+specshield compare base.yaml target.yaml --remote
+```
+
+### Remote compare with CI fail on breaking changes
+
+```bash
+specshield compare base.yaml target.yaml --remote --fail-on-breaking
+```
+
+### Remote compare with JSON output
+
+```bash
+specshield compare base.yaml target.yaml --remote --json --output result.json
+```
+
+### How authentication works in remote mode
+
+The CLI reads your API token (from flag, env var, or stored config) and sends it as an `X-Api-Key` header with each request. If no token is found, the command exits with an error:
+
+```
+Error: No API key found. Run: specshield login --api-key <KEY>
+```
+
+---
 
 ## Config File
 
-Create `.specshield.yml` in your project root:
+Create `.specshield.yml` in your project root to set default behavior:
 
 ```yaml
-allowBreakingChanges: false
 failOnBreaking: true
+allowBreakingChanges: false
+severity: error
 
 ignore:
-  - "User.email removed"
-  - "/admin DELETE removed"
-
-severity: error
+  - "DELETE /admin removed"
+  - "User.internal_id removed"
 
 remote:
   enabled: false
-  url: "https://api.specshield.io/compare"
+  url: "https://specshield.io/compare"
   timeout: 10000
+  apiKey: ""        # prefer env var or specshield login instead
+```
+
+CLI flags always override config file values.
+
+---
+
+## All Options
+
+```bash
+specshield compare <base> <target> [options]
 ```
 
-> CLI arguments always override config file values.
+| Option | Description |
+|---|---|
+| `--remote` | Use the SpecShield hosted compare API |
+| `--api-key <key>` | API token for remote mode (overrides env and stored config) |
+| `--remote-url <url>` | Override the hosted API base URL |
+| `--fail-on-breaking` | Exit code 1 if breaking changes are found |
+| `--allow-breaking` | Override fail-on-breaking |
+| `--json` | Output machine-readable JSON |
+| `--output <file>` | Save result to a file |
+| `--ignore <change>` | Ignore a specific change string (repeatable) |
+| `--severity <level>` | Minimum severity: `info` / `warning` / `error` |
+| `--config <path>` | Path to `.specshield.yml` |
+| `--timeout <ms>` | Request timeout for remote mode (default: 10000) |
+
+---
 
 ## Exit Codes
 
 | Code | Meaning |
 |---|---|
 | `0` | Success — no blocking issues |
-| `1` | Breaking changes found and `--fail-on-breaking` active |
-| `2` | Invalid input, config error, or runtime error |
+| `1` | Breaking changes found and `--fail-on-breaking` is active |
+| `2` | Invalid input, missing token, config error, or runtime error |
+
+---
 
 ## CI/CD — GitHub Actions
 
+### Local compare (no token required)
+
 ```yaml
 name: API Contract Check
 
@@ -169,7 +275,6 @@ jobs:
 
       - run: npm install -g specshield
 
-      # Option A: spec files are committed to the repo
       - name: Get base spec from main branch
         run: git show origin/main:api/openapi.yaml > /tmp/base-spec.yaml
 
@@ -187,22 +292,31 @@ jobs:
           path: spec-diff.json
 ```
 
-> **Note:** Some projects generate their OpenAPI spec dynamically (e.g. from Spring Boot annotations, FastAPI, etc.) instead of storing a static file. In that case, add a build step before the compare step to generate the spec from your code.
+### Remote compare (with SpecShield hosted API)
 
-## Running Locally
+Add your API token as a GitHub Actions secret named `SPECSHIELD_API_KEY`, then:
 
-```bash
-npm install
-npm link
-specshield compare fixtures/spec-v1.yaml fixtures/spec-v2.yaml --fail-on-breaking
+```yaml
+      - name: Compare specs (remote)
+        env:
+          SPECSHIELD_API_KEY: ${{ secrets.SPECSHIELD_API_KEY }}
+        run: |
+          specshield compare /tmp/base-spec.yaml api/openapi.yaml \
+            --remote \
+            --fail-on-breaking \
+            --output spec-diff.json
 ```
 
-## Running Tests
+> **Note:** If your project generates its OpenAPI spec dynamically (e.g. Spring Boot, FastAPI), add a build step before the compare step to generate the spec from your code.
 
-```bash
-npm test
-```
+---
 
 ## License
 
 MIT © Deepak Satyam
+
+---
+
+## Support
+
+Questions or issues? Reach out at [admin@specshield.io](mailto:admin@specshield.io) or open an issue on GitHub.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specshield",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI to compare OpenAPI/Swagger specs and detect breaking changes for CI/CD pipelines and local developer workflows.",
   "main": "src/cli.js",
   "bin": {

package/src/commands/compare.js

@@ -16,7 +16,7 @@ const logger = require('../utils/logger');
 const fsExtra = require('fs-extra');
 const { getStoredApiKey } = require('../config/localConfig');
 
-const HOSTED_API_URL = 'http://specshield.io';
+const HOSTED_API_URL = 'https://specshield.io';
 
 const compare = new Command('compare');
 

package/src/commands/login.js

@@ -6,7 +6,7 @@ const ora = require('ora');
 const axios = require('axios');
 const { setStoredApiKey, CONFIG_PATH } = require('../config/localConfig');
 
-const HOSTED_API_URL = 'http://specshield.io';
+const HOSTED_API_URL = 'https://specshield.io';
 
 const login = new Command('login');