specshield 1.0.0 → 1.0.3

package/README.md

@@ -1,16 +1,66 @@
-# SpecShield CLI
+# 🚀 SpecShield — OpenAPI Diff & Breaking Change Detection CLI
 
-> Compare OpenAPI specs and detect breaking changes — designed for CI/CD and local developer workflows.
+![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)
 
-## Features
+Compare OpenAPI and Swagger specs, detect breaking changes, and fail CI before incompatible API changes reach production.
 
-- Detect breaking changes, additions, and modifications between two OpenAPI specs
-- Support YAML and JSON specs
-- CI/CD-ready with exit code control (`--fail-on-breaking`)
-- Config file support (`.specshield.yml`)
-- JSON output for machine parsing
-- Ignore list to suppress known changes
-- Placeholder remote mode for future SaaS backend integration
+
+## 📌 What is SpecShield?
+
+SpecShield is a CLI tool that compares two OpenAPI/Swagger specifications and detects:
+
+- ❌ Breaking changes
+- ➕ Additions
+- 🔄 Modifications
+
+It is designed for:
+- CI/CD pipelines
+- Backend developers
+- API governance teams
+- Local development workflows
+
+---
+
+## ❗ Why SpecShield?
+
+API changes can silently break:
+- Mobile apps
+- Frontend clients
+- Partner integrations
+- Internal microservices
+
+Manual API review is:
+- ❌ Error-prone
+- ❌ Time-consuming
+- ❌ Not scalable
+
+👉 SpecShield solves this by automating API contract validation.
+
+---
+
+## 🎯 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
+
+---
+
+## ✨ 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
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "specshield",
-  "version": "1.0.0",
-  "description": "CLI tool to compare OpenAPI specs and detect breaking changes",
+  "version": "1.0.3",
+  "description": "CLI to compare OpenAPI/Swagger specs and detect breaking changes for CI/CD pipelines and local developer workflows.",
   "main": "src/cli.js",
   "bin": {
     "specshield": "./bin/specshield.js"
@@ -12,9 +12,37 @@
     "test:watch": "jest --watch",
     "lint": "eslint src tests --ext .js"
   },
-  "keywords": ["openapi", "api", "breaking-changes", "cli", "specshield"],
+  "keywords": [
+    "openapi",
+    "swagger",
+    "openapi-diff",
+    "swagger-diff",
+    "api-diff",
+    "api-breaking-changes",
+    "breaking-change-detection",
+    "contract-testing",
+    "api-contract",
+    "api-versioning",
+    "api-governance",
+    "ci-cd",
+    "devops",
+    "github-actions",
+    "automation",
+    "cli",
+    "developer-tools",
+    "yaml",
+    "json",
+    "schema-diff",
+    "rest-api",
+    "openapi-cli"
+  ],
   "license": "MIT",
-  "files": ["bin", "src", "README.md", "LICENSE"],
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
     "axios": "^1.6.7",
     "chalk": "^4.1.2",
@@ -28,8 +56,12 @@
   },
   "jest": {
     "testEnvironment": "node",
-    "testMatch": ["**/tests/**/*.test.js"],
-    "collectCoverageFrom": ["src/**/*.js"]
+    "testMatch": [
+      "**/tests/**/*.test.js"
+    ],
+    "collectCoverageFrom": [
+      "src/**/*.js"
+    ]
   },
   "engines": {
     "node": ">=20.0.0"

package/src/cli.js

@@ -3,6 +3,8 @@
 const { Command } = require('commander');
 const { version } = require('../package.json');
 const compareCommand = require('./commands/compare');
+const loginCommand = require('./commands/login');
+const logoutCommand = require('./commands/logout');
 
 const program = new Command();
 
@@ -12,6 +14,8 @@ program
   .version(version);
 
 program.addCommand(compareCommand);
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
 
 program.parseAsync(process.argv).catch((err) => {
   const logger = require('./utils/logger');

package/src/commands/compare.js

@@ -14,6 +14,9 @@ const { loadConfig } = require('../core/configLoader');
 const { resolveExitCode } = require('../core/exitCode');
 const logger = require('../utils/logger');
 const fsExtra = require('fs-extra');
+const { getStoredApiKey } = require('../config/localConfig');
+
+const HOSTED_API_URL = 'https://api.specshield.io';
 
 const compare = new Command('compare');
 
@@ -28,7 +31,9 @@ compare
   .option('--config <path>', 'Path to .specshield.yml config file')
   .option('--ignore <change>', 'Ignore a specific change string (repeatable)', collect, [])
   .option('--severity <level>', 'Minimum severity level: info | warning | error', 'error')
-  .option('--remote-url <url>', 'Remote API endpoint for comparison')
+  .option('--remote', 'Use the SpecShield hosted compare API')
+  .option('--api-key <key>', 'API key for hosted mode (overrides env and stored config)')
+  .option('--remote-url <url>', 'Override the hosted API base URL')
   .option('--timeout <ms>', 'Request timeout for remote mode (ms)', '10000')
   .action(async (base, target, opts) => {
     try {
@@ -38,11 +43,25 @@ compare
       // Merge config with CLI options (CLI wins)
       const options = mergeOptions(config, opts);
 
+      // Resolve API key for remote mode (precedence: --api-key > env > stored config > .specshield.yml)
+      if (options.remote || options.remoteUrl || (config.remote && config.remote.enabled)) {
+        options.resolvedApiKey = opts.apiKey
+          || process.env.SPECSHIELD_API_KEY
+          || await getStoredApiKey()
+          || (config.remote && config.remote.apiKey)
+          || null;
+
+        if (!options.resolvedApiKey) {
+          logger.error('No API key found. Run: specshield login --api-key <KEY>');
+          process.exit(2);
+        }
+      }
+
       const spinner = options.json ? null : ora('Loading specs...').start();
 
       let result;
 
-      if (options.remoteUrl || (config.remote && config.remote.enabled)) {
+      if (options.remote || options.remoteUrl || (config.remote && config.remote.enabled)) {
         result = await runRemoteComparison(base, target, options, spinner);
       } else {
         result = await runLocalComparison(base, target, options, spinner);
@@ -107,22 +126,29 @@ async function runLocalComparison(base, target, options, spinner) {
 
 async function runRemoteComparison(base, target, options, spinner) {
   const axios = require('axios');
-  const { loadSpec } = require('../core/loadSpec');
+  const { version } = require('../../package.json');
 
   if (spinner) spinner.text = 'Loading specs for remote comparison...';
   const baseRaw = await loadSpec(base);
   const targetRaw = await loadSpec(target);
 
-  const url = options.remoteUrl || (options.remote && options.remote.url);
+  const url = options.remoteUrl || HOSTED_API_URL + '/compare';
   const timeout = parseInt(options.timeout, 10) || 10000;
 
-  if (spinner) spinner.text = `Sending to remote: ${url}`;
+  if (spinner) spinner.text = `Sending to hosted API...`;
+
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Api-Key': options.resolvedApiKey,
+    'X-SpecShield-Client': 'cli',
+    'X-SpecShield-Version': version,
+  };
 
   try {
     const response = await axios.post(
       url,
       { baseSpec: baseRaw, targetSpec: targetRaw },
-      { timeout, headers: { 'Content-Type': 'application/json' } }
+      { timeout, headers }
     );
     return response.data;
   } catch (err) {
@@ -167,7 +193,8 @@ function mergeOptions(config, cliOpts) {
       ...(config.ignore || []),
     ],
     severity: cliOpts.severity || config.severity || 'error',
-    remoteUrl: cliOpts.remoteUrl || (config.remote && config.remote.enabled ? config.remote.url : null),
+    remote: cliOpts.remote || (config.remote && config.remote.enabled) || false,
+    remoteUrl: cliOpts.remoteUrl || null,
     timeout: cliOpts.timeout || (config.remote && config.remote.timeout) || 10000,
   };
 }

package/src/commands/login.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const axios = require('axios');
+const { setStoredApiKey, CONFIG_PATH } = require('../config/localConfig');
+
+const HOSTED_API_URL = 'https://api.specshield.io';
+
+const login = new Command('login');
+
+login
+  .description('Authenticate with the SpecShield hosted API using your API key')
+  .requiredOption('--api-key <key>', 'Your SpecShield API key (starts with ss_)')
+  .option('--api-url <url>', 'Override the hosted API base URL', HOSTED_API_URL)
+  .action(async (opts) => {
+    const spinner = ora('Validating API key...').start();
+
+    try {
+      const response = await axios.post(
+        `${opts.apiUrl}/auth/validate-api-key`,
+        {},
+        {
+          headers: { 'X-Api-Key': opts.apiKey },
+          timeout: 10000,
+        }
+      );
+
+      if (!response.data.valid) {
+        spinner.fail(chalk.red('API key is invalid.'));
+        process.exit(1);
+      }
+
+      await setStoredApiKey(opts.apiKey);
+
+      spinner.succeed(chalk.green('Logged in successfully.'));
+      console.log('');
+      console.log(`  ${chalk.bold('Customer:')}  ${response.data.name}`);
+      console.log(`  ${chalk.bold('Plan:')}      ${response.data.plan}`);
+      console.log(`  ${chalk.gray('Config:')}    ${CONFIG_PATH}`);
+      console.log('');
+      console.log(chalk.gray('  Run: specshield compare base.yaml target.yaml --remote'));
+
+    } catch (err) {
+      const msg = err.response
+        ? `Validation failed (${err.response.status}): ${JSON.stringify(err.response.data)}`
+        : `Connection error: ${err.message}`;
+      spinner.fail(chalk.red(msg));
+      process.exit(1);
+    }
+  });
+
+module.exports = login;

package/src/commands/logout.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const { clearStoredApiKey } = require('../config/localConfig');
+
+const logout = new Command('logout');
+
+logout
+  .description('Remove your stored SpecShield API key')
+  .action(async () => {
+    await clearStoredApiKey();
+    console.log(chalk.green('Logged out. API key removed from local config.'));
+  });
+
+module.exports = logout;

package/src/config/localConfig.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fsExtra = require('fs-extra');
+
+const CONFIG_PATH = path.join(os.homedir(), '.specshield', 'config.json');
+
+async function loadLocalConfig() {
+  try {
+    return await fsExtra.readJson(CONFIG_PATH);
+  } catch {
+    return {};
+  }
+}
+
+async function saveLocalConfig(data) {
+  await fsExtra.outputJson(CONFIG_PATH, data, { spaces: 2 });
+}
+
+async function getStoredApiKey() {
+  const config = await loadLocalConfig();
+  return config.apiKey || null;
+}
+
+async function setStoredApiKey(apiKey) {
+  const config = await loadLocalConfig();
+  config.apiKey = apiKey;
+  await saveLocalConfig(config);
+}
+
+async function clearStoredApiKey() {
+  const config = await loadLocalConfig();
+  delete config.apiKey;
+  await saveLocalConfig(config);
+}
+
+module.exports = { loadLocalConfig, saveLocalConfig, getStoredApiKey, setStoredApiKey, clearStoredApiKey, CONFIG_PATH };