@apidiffguard/cli 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APIDiffGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# `@apidiffguard/cli`
+
+Command-line JSON / API response diff for CI and local checks. Uses the same engine as APIDiffGuard Cloud (`@apidiffguard/diff`).
+
+## Install (from this repo)
+
+```bash
+cd packages/diff-engine && npm run build && cd -
+cd packages/cli && npm install
+```
+
+Or from the repo root after workspaces are linked:
+
+```bash
+npx apidiff check --baseline old.json --current new.json --fail-on breaking
+```
+
+## Usage
+
+```bash
+# Compare two files
+apidiff check --baseline baseline.json --current live.json --fail-on breaking
+
+# Compare a baseline file to a live URL
+apidiff check --baseline baseline.json --url https://httpbin.org/json --fail-on warning
+
+# Machine-readable output
+apidiff check --baseline a.json --current b.json --json
+```
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | No changes at or above `--fail-on` |
+| 1 | Failing severity found |
+| 2 | Usage / runtime error |
+
+`--fail-on` accepts `breaking` (default), `warning`, or `info`.

package/bin/apidiff.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { compareJson, summarizeChanges } from "@apidiffguard/diff";
+
+const VERSION = "0.3.0";
+
+function printHelp() {
+  console.log(`apidiff ${VERSION} — APIDiffGuard CLI
+
+Usage:
+  apidiff check --baseline <file> --current <file> [options]
+  apidiff check --baseline <file> --url <https://...> [options]
+  apidiff --version
+  apidiff --help
+
+Options:
+  --fail-on breaking|warning|info   Severity threshold (default: breaking)
+  --schema-only                     Ignore leaf value churn
+  --header "Name: value"            Repeatable request header for --url
+  --json                            Print structured JSON
+
+Exit codes:
+  0  no changes at or above --fail-on severity
+  1  failing severity found
+  2  usage / runtime error
+`);
+}
+
+function parseArgs(argv) {
+  const out = {
+    cmd: null,
+    baseline: null,
+    current: null,
+    url: null,
+    failOn: "breaking",
+    schemaOnly: false,
+    headers: /** @type {Record<string, string>} */ ({}),
+    json: false,
+    help: false,
+    version: false,
+  };
+  const args = [...argv];
+  if (args[0] && !args[0].startsWith("-")) {
+    out.cmd = args.shift();
+  }
+  while (args.length) {
+    const a = args.shift();
+    if (a === "--help" || a === "-h") out.help = true;
+    else if (a === "--version" || a === "-v") out.version = true;
+    else if (a === "--baseline" || a === "--old") out.baseline = args.shift() ?? null;
+    else if (a === "--current" || a === "--new") out.current = args.shift() ?? null;
+    else if (a === "--url") out.url = args.shift() ?? null;
+    else if (a === "--fail-on") out.failOn = (args.shift() ?? "breaking").toLowerCase();
+    else if (a === "--schema-only") out.schemaOnly = true;
+    else if (a === "--header" || a === "-H") {
+      const raw = args.shift();
+      if (!raw) throw new Error("--header requires \"Name: value\"");
+      const idx = raw.indexOf(":");
+      if (idx <= 0) throw new Error(`Invalid --header (expected Name: value): ${raw}`);
+      const name = raw.slice(0, idx).trim();
+      const value = raw.slice(idx + 1).trim();
+      if (!name) throw new Error(`Invalid --header name: ${raw}`);
+      out.headers[name] = value;
+    } else if (a === "--json") out.json = true;
+    else {
+      throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+  return out;
+}
+
+function readJsonFile(path) {
+  const abs = resolve(path);
+  if (!existsSync(abs)) throw new Error(`File not found: ${abs}`);
+  try {
+    return JSON.parse(readFileSync(abs, "utf8"));
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${abs}: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+async function fetchJson(url, headers = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Only http/https URLs are allowed.");
+  }
+  const res = await fetch(url, {
+    headers: {
+      Accept: "application/json, text/plain, */*",
+      ...headers,
+    },
+    redirect: "follow",
+    signal: AbortSignal.timeout(30_000),
+  });
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(
+      `URL did not return JSON (HTTP ${res.status}). Body starts with: ${text.slice(0, 120)}`
+    );
+  }
+}
+
+const RANK = { info: 0, warning: 1, breaking: 2 };
+
+async function runCheck(opts) {
+  if (!opts.baseline) throw new Error("--baseline <file> is required");
+  if (!opts.current && !opts.url) {
+    throw new Error("Provide --current <file> or --url <https://...>");
+  }
+  if (opts.current && opts.url) {
+    throw new Error("Use either --current or --url, not both");
+  }
+  if (!["breaking", "warning", "info"].includes(opts.failOn)) {
+    throw new Error("--fail-on must be breaking, warning, or info");
+  }
+
+  const baseline = readJsonFile(opts.baseline);
+  const current = opts.url
+    ? await fetchJson(opts.url, opts.headers)
+    : readJsonFile(opts.current);
+
+  const changes = compareJson(baseline, current, {
+    schemaOnly: opts.schemaOnly,
+    arrayIdentity: true,
+  });
+  const summary = summarizeChanges(changes);
+  const threshold = RANK[opts.failOn];
+  const failing = changes.filter((c) => RANK[c.severity] >= threshold);
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          summary,
+          failOn: opts.failOn,
+          schemaOnly: opts.schemaOnly,
+          failed: failing.length > 0,
+          changes,
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.log(
+      `breaking=${summary.breakingCount} warning=${summary.warningCount} info=${summary.infoCount}${opts.schemaOnly ? " (schema-only)" : ""}`
+    );
+    for (const c of changes.slice(0, 50)) {
+      const tag = c.severity.toUpperCase().padEnd(8);
+      console.log(`${tag} ${c.type.padEnd(13)} ${c.path}`);
+    }
+    if (changes.length > 50) {
+      console.log(`… ${changes.length - 50} more`);
+    }
+    if (failing.length) {
+      console.log(
+        `\nFailed: ${failing.length} change(s) at or above ${opts.failOn}.`
+      );
+    } else {
+      console.log(`\nPassed: no changes at or above ${opts.failOn}.`);
+    }
+  }
+
+  return failing.length ? 1 : 0;
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    printHelp();
+    process.exit(2);
+  }
+
+  if (opts.version) {
+    console.log(VERSION);
+    return;
+  }
+  if (opts.help || !opts.cmd) {
+    printHelp();
+    return;
+  }
+
+  if (opts.cmd !== "check") {
+    console.error(`Unknown command: ${opts.cmd}`);
+    printHelp();
+    process.exit(2);
+  }
+
+  try {
+    const code = await runCheck(opts);
+    process.exit(code);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(2);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@apidiffguard/cli",
+  "version": "0.3.0",
+  "description": "CLI for APIDiffGuard — diff API JSON responses and fail CI on breaking changes.",
+  "type": "module",
+  "bin": {
+    "apidiff": "./bin/apidiff.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "apidiff": "node ./bin/apidiff.js"
+  },
+  "dependencies": {
+    "@apidiffguard/diff": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api",
+    "diff",
+    "breaking-change",
+    "ci",
+    "json",
+    "apidiffguard"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orvi2014/apidiffguard.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/orvi2014/apidiffguard/tree/main/packages/cli",
+  "bugs": {
+    "url": "https://github.com/orvi2014/apidiffguard/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}