specdrift-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Bridges
+
+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,115 @@
+# specdrift
+
+Point it at a live API and its own OpenAPI spec. It tells you where they've
+drifted apart. Free, zero-dependency, MIT-licensed, GET-only.
+
+## What it does
+
+For every `GET` operation in your OpenAPI 3.x spec, specdrift:
+
+1. builds a real request from the spec's own declared parameter
+   examples/defaults (path and query params — it never guesses a value that
+   isn't in the spec),
+2. calls your live API,
+3. compares the actual response against the spec: status code declared?
+   required fields present? field types matching (`string`/`number`/
+   `integer`/`boolean`/`array`/`object`)? any undeclared extra fields?
+
+...and prints a plain-text report. Nothing is mutated, nothing is stored,
+nothing is sent anywhere except your own API.
+
+**Safety note:** specdrift only ever sends `GET` requests. It will not call
+`POST`/`PUT`/`PATCH`/`DELETE` on your API, even if your spec declares them —
+running an unattended tool against arbitrary mutating endpoints on someone's
+live system is a real risk, not a hypothetical one, so v1 deliberately
+doesn't do it.
+
+## Usage
+
+Not yet published to npm, so for now, clone and run directly:
+
+```bash
+git clone https://github.com/MattBridges/specdrift.git
+cd specdrift/cli   # if running from this monorepo path, otherwise cli/ is the root
+node bin/specdrift.js path/to/openapi.json https://api.example.com
+```
+
+```
+specdrift <spec.json> <baseUrl> [--path <regex>] [--timeout <ms>]
+```
+
+- `<spec.json>` — a local path or URL to an OpenAPI 3.x **JSON** document
+  (YAML is a known v1 gap — see below, it fails loudly rather than silently
+  misparsing).
+- `<baseUrl>` — the live API to check.
+- `--path <regex>` — only check paths matching this regex.
+- `--timeout <ms>` — per-request timeout, default 10000.
+
+Exit codes: `0` = no drift found, `1` = drift found in at least one
+endpoint, `2` = specdrift itself couldn't run (bad spec, no checkable
+endpoints, etc.) — matches the convention used across United Front Labs'
+other free CLIs (see
+[d1-migration-guard](https://github.com/MattBridges/d1-migration-guard)) so
+CI usage (`specdrift ... || exit 1`) is predictable across tools.
+
+Requires Node.js >= 18 (uses the built-in `fetch`). Zero npm dependencies.
+
+## Example
+
+```
+$ specdrift openapi.json https://api.example.com
+
+specdrift: checking 3 GET endpoint(s) against https://api.example.com
+
+OK    GET /widgets -- 200 matches spec (declared: 200)
+DRIFT GET /widgets/{id} -- 200 (matched "200")
+        $.price: type mismatch -- spec declares "number", actual response has "string"
+  info  $.sku: field present in actual response but not declared in spec
+SKIP  GET /orders/{id} -- path parameter "id" has no example/default value to substitute
+
+specdrift: 2 checked, 1 with drift, 1 skipped, 0 request error(s).
+```
+
+## Status: v0.1, verified against real behavior
+
+Verified end-to-end with a local fixture HTTP server (`test/fixtures/`) run
+under a real Node process, in two modes: a spec-conformant server (expect
+exit 0, zero findings) and a deliberately drifted one (missing required
+field, extra undeclared field, wrong field type, and an undeclared status
+code — all four correctly detected with the right exit code). Not tested
+against every real-world OpenAPI dialect quirk (e.g. `oneOf`/`anyOf`/
+`allOf`, `nullable`, deep array recursion beyond the first item) — those are
+either skipped safely (no false "drift") or a documented gap, not silently
+mishandled.
+
+## Known v1 limitations (documented, not hidden)
+
+- OpenAPI JSON only — no YAML parsing (adding a real YAML parser without a
+  dependency is nontrivial; a "known gap" beats a buggy hand-rolled parser).
+- GET-only — no coverage of mutating operations, by design (see Safety note
+  above).
+- Path/query parameters need an `example`, `schema.example`,
+  `schema.default`, or `schema.enum` in the spec to be tested; parameters
+  with none of those are skipped and reported as `SKIP`, not silently
+  dropped or guessed.
+- Object/array schema comparison recurses up to 3 levels deep and checks
+  only the first item of an array — enough to catch the drift that actually
+  happens in practice (renamed/removed/retyped fields), not a full JSON
+  Schema validator.
+- `oneOf`/`anyOf`/`allOf`/`nullable` and other advanced JSON Schema
+  keywords are not evaluated (no false positives — those fields are simply
+  not checked, and this is expected v1 behavior, not a hidden bug).
+
+## Why this exists
+
+This CLI is a free companion to [SpecDrift](https://mattbridges.github.io/specdrift/),
+a hosted contract-drift monitor concept (continuous checks + AI-written
+plain-language change summaries posted to Slack/PR comments). The free CLI
+gives you a real, usable one-shot check today with zero signup; the hosted
+version (still pre-launch, [waitlist here](https://mattbridges.github.io/specdrift/))
+would run this continuously and explain *why* drift matters, not just that
+it happened.
+
+## License
+
+MIT

package/bin/specdrift.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+const { loadSpec } = require('../src/spec');
+const { listCheckableEndpoints, buildRequest } = require('../src/endpoints');
+const { diffResponse } = require('../src/diff');
+
+function printHelp() {
+  console.log(`specdrift -- check a live API against its own OpenAPI spec
+
+Usage:
+  specdrift <spec.json> <baseUrl> [options]
+
+  <spec.json>   Path or URL to an OpenAPI 3.x JSON document
+  <baseUrl>     Base URL of the live API to check, e.g. https://api.example.com
+
+Options:
+  --path <regex>   Only check paths matching this regex
+  --timeout <ms>    Per-request timeout in milliseconds (default 10000)
+  -h, --help        Show this help
+
+specdrift only sends GET requests. It never calls POST/PUT/PATCH/DELETE against
+your live API. Exit codes: 0 = no drift found, 1 = drift found, 2 = could not run.
+
+Docs: https://github.com/MattBridges/specdrift`);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') args.help = true;
+    else if (a === '--path') args.pathFilter = argv[++i];
+    else if (a === '--timeout') args.timeout = Number(argv[++i]);
+    else args._.push(a);
+  }
+  return args;
+}
+
+async function fetchWithTimeout(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { accept: 'application/json' } });
+    const contentType = res.headers.get('content-type') || '';
+    let body = null;
+    if (contentType.includes('application/json')) {
+      try {
+        body = await res.json();
+      } catch {
+        body = null;
+      }
+    }
+    return { status: res.status, body };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || args._.length < 2) {
+    printHelp();
+    process.exit(args.help ? 0 : 2);
+  }
+
+  const [specArg, baseUrlArg] = args._;
+  const timeout = Number.isFinite(args.timeout) && args.timeout > 0 ? args.timeout : 10000;
+  const baseUrl = baseUrlArg.replace(/\/+$/, '');
+
+  let spec;
+  try {
+    spec = await loadSpec(specArg);
+  } catch (err) {
+    console.error(`specdrift: ${err.message}`);
+    process.exit(2);
+  }
+
+  let endpoints = listCheckableEndpoints(spec);
+  if (args.pathFilter) {
+    const re = new RegExp(args.pathFilter);
+    endpoints = endpoints.filter((e) => re.test(e.pathTemplate));
+  }
+
+  if (endpoints.length === 0) {
+    console.error('specdrift: no checkable GET endpoints found (after filtering, if any).');
+    process.exit(2);
+  }
+
+  let driftCount = 0;
+  let checkedCount = 0;
+  let skippedCount = 0;
+  let errorCount = 0;
+
+  console.log(`specdrift: checking ${endpoints.length} GET endpoint(s) against ${baseUrl}\n`);
+
+  for (const endpoint of endpoints) {
+    const built = buildRequest(endpoint);
+    if (built.skipped) {
+      skippedCount++;
+      console.log(`SKIP  ${endpoint.method} ${endpoint.pathTemplate} -- ${built.skipped}`);
+      continue;
+    }
+
+    const url = baseUrl + built.pathStr;
+    let response;
+    try {
+      response = await fetchWithTimeout(url, timeout);
+    } catch (err) {
+      errorCount++;
+      console.log(`ERROR ${endpoint.method} ${endpoint.pathTemplate} -- request failed: ${err.message}`);
+      continue;
+    }
+
+    checkedCount++;
+    const { findings, matchedStatus, declaredStatuses } = diffResponse(spec, endpoint, response.status, response.body);
+    const errors = findings.filter((f) => f.level === 'error');
+    const infos = findings.filter((f) => f.level === 'info');
+
+    if (errors.length === 0) {
+      console.log(`OK    ${endpoint.method} ${endpoint.pathTemplate} -- ${response.status} matches spec (declared: ${declaredStatuses.join(', ')})`);
+    } else {
+      driftCount++;
+      console.log(`DRIFT ${endpoint.method} ${endpoint.pathTemplate} -- ${response.status}${matchedStatus ? ` (matched "${matchedStatus}")` : ''}`);
+      for (const f of errors) {
+        console.log(`        ${f.path}: ${f.message}`);
+      }
+    }
+    for (const f of infos) {
+      console.log(`  info  ${f.path}: ${f.message}`);
+    }
+  }
+
+  console.log(
+    `\nspecdrift: ${checkedCount} checked, ${driftCount} with drift, ${skippedCount} skipped, ${errorCount} request error(s).`
+  );
+
+  if (errorCount > 0 && checkedCount === 0) process.exit(2);
+  process.exit(driftCount > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(`specdrift: unexpected error -- ${err.stack || err.message}`);
+  process.exit(2);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "specdrift-cli",
+  "version": "0.1.0",
+  "description": "Check a live API against its own OpenAPI spec and report drift: undocumented status codes, missing required fields, and type mismatches.",
+  "license": "MIT",
+  "bin": {
+    "specdrift": "./bin/specdrift.js"
+  },
+  "main": "./src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MattBridges/specdrift.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/MattBridges/specdrift/tree/main/cli",
+  "bugs": {
+    "url": "https://github.com/MattBridges/specdrift/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "keywords": [
+    "openapi",
+    "api",
+    "contract-testing",
+    "drift-detection",
+    "api-monitoring",
+    "devtools"
+  ]
+}

package/src/diff.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const { resolveSchema } = require('./spec');
+
+const JSON_TYPE_OF = (value) => {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value === 'number' ? 'number' : typeof value;
+};
+
+function typeMatches(declaredType, actualJsType, actualValue) {
+  if (declaredType === 'integer') {
+    return actualJsType === 'number' && Number.isInteger(actualValue);
+  }
+  if (declaredType === 'number') return actualJsType === 'number';
+  if (declaredType === 'string') return actualJsType === 'string';
+  if (declaredType === 'boolean') return actualJsType === 'boolean';
+  if (declaredType === 'array') return actualJsType === 'array';
+  if (declaredType === 'object') return actualJsType === 'object';
+  return true; // unknown/unspecified declared type -- nothing to compare against
+}
+
+// Walks one level of an object schema against an actual value and returns a
+// flat list of drift findings for that node. Recurses into declared object
+// properties; does not attempt full recursive array-item diffing beyond the
+// first element, since that is where nearly all real-world contract drift
+// (renamed/removed/retyped fields) actually shows up, and going further would
+// mostly add noise for a v1 tool.
+function diffValue(spec, schema, value, path, findings, depth = 0) {
+  const resolved = resolveSchema(spec, schema);
+  if (!resolved || typeof resolved !== 'object' || Object.keys(resolved).length === 0) {
+    return; // no usable schema to compare against
+  }
+
+  if (value === undefined) {
+    findings.push({ level: 'error', path, message: 'declared in spec response but missing from actual response' });
+    return;
+  }
+
+  const declaredType = resolved.type;
+  const actualJsType = JSON_TYPE_OF(value);
+  if (declaredType && !typeMatches(declaredType, actualJsType, value)) {
+    findings.push({
+      level: 'error',
+      path,
+      message: `type mismatch -- spec declares "${declaredType}", actual response has "${actualJsType}"`,
+    });
+    return;
+  }
+
+  if (declaredType === 'object' || (!declaredType && resolved.properties)) {
+    const props = resolved.properties || {};
+    const required = resolved.required || [];
+    const actualObj = value && typeof value === 'object' ? value : {};
+    for (const key of required) {
+      if (!(key in actualObj)) {
+        findings.push({ level: 'error', path: `${path}.${key}`, message: 'required field missing from actual response' });
+      }
+    }
+    if (depth < 3) {
+      for (const [key, subSchema] of Object.entries(props)) {
+        if (key in actualObj) {
+          diffValue(spec, subSchema, actualObj[key], `${path}.${key}`, findings, depth + 1);
+        }
+      }
+    }
+    if (resolved.additionalProperties === false) {
+      for (const key of Object.keys(actualObj)) {
+        if (!(key in props)) {
+          findings.push({
+            level: 'error',
+            path: `${path}.${key}`,
+            message: 'field present in actual response but not declared in spec, and spec forbids additional properties',
+          });
+        }
+      }
+    } else {
+      for (const key of Object.keys(actualObj)) {
+        if (!(key in props)) {
+          findings.push({
+            level: 'info',
+            path: `${path}.${key}`,
+            message: 'field present in actual response but not declared in spec',
+          });
+        }
+      }
+    }
+  } else if (declaredType === 'array' && resolved.items && Array.isArray(value) && value.length > 0) {
+    diffValue(spec, resolved.items, value[0], `${path}[0]`, findings, depth + 1);
+  }
+}
+
+// Compares one live HTTP response against the OpenAPI spec's declared responses
+// for an operation. Returns { findings, matchedStatus, declaredStatuses }.
+function diffResponse(spec, endpoint, actualStatus, actualBody) {
+  const findings = [];
+  const declaredStatuses = Object.keys(endpoint.responses);
+  const key = declaredStatuses.includes(String(actualStatus)) ? String(actualStatus) : 'default';
+  const matched = endpoint.responses[key];
+
+  if (!matched) {
+    findings.push({
+      level: 'error',
+      path: '(status)',
+      message: `actual response status ${actualStatus} is not declared in the spec (declared: ${declaredStatuses.join(', ') || 'none'})`,
+    });
+    return { findings, matchedStatus: null, declaredStatuses };
+  }
+
+  const jsonContent = matched.content && matched.content['application/json'];
+  if (jsonContent && jsonContent.schema) {
+    diffValue(spec, jsonContent.schema, actualBody, '$', findings);
+  }
+  return { findings, matchedStatus: key, declaredStatuses };
+}
+
+module.exports = { diffResponse };

package/src/endpoints.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const { resolveRef } = require('./spec');
+
+const CHECKABLE_METHODS = ['get'];
+
+// Only GET operations are exercised. specdrift never sends POST/PUT/PATCH/DELETE
+// against a live target -- this is a safety check tool, not a load-testing or
+// fuzzing tool, and calling mutating endpoints on someone's real API without
+// consent would be a real-world harm, not a hypothetical one.
+function listCheckableEndpoints(spec) {
+  const endpoints = [];
+  const paths = spec.paths || {};
+  for (const [pathTemplate, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+    const pathLevelParams = pathItem.parameters || [];
+    for (const method of CHECKABLE_METHODS) {
+      const op = pathItem[method];
+      if (!op) continue;
+      const params = [...pathLevelParams, ...(op.parameters || [])].map((p) =>
+        p.$ref ? resolveRef(spec, p.$ref) : p
+      );
+      endpoints.push({
+        pathTemplate,
+        method: method.toUpperCase(),
+        operationId: op.operationId || `${method.toUpperCase()} ${pathTemplate}`,
+        params,
+        responses: op.responses || {},
+      });
+    }
+  }
+  return endpoints;
+}
+
+// Builds a concrete request (path + query string) from an endpoint's declared
+// parameters, using each parameter's `example` or `schema.default`/`schema.example`
+// as the value. Returns { skipped: reason } if a required parameter has no
+// usable example value -- specdrift will not guess (e.g. inventing a fake user ID),
+// since a wrong guess could produce a misleading drift report.
+function buildRequest(endpoint) {
+  let pathStr = endpoint.pathTemplate;
+  const query = [];
+  for (const param of endpoint.params) {
+    const value = exampleValueFor(param);
+    if (param.in === 'path') {
+      if (value === undefined) {
+        return { skipped: `path parameter "${param.name}" has no example/default value to substitute` };
+      }
+      pathStr = pathStr.replace(`{${param.name}}`, encodeURIComponent(String(value)));
+    } else if (param.in === 'query') {
+      if (value === undefined) {
+        if (param.required) {
+          return { skipped: `required query parameter "${param.name}" has no example/default value` };
+        }
+        continue;
+      }
+      query.push(`${encodeURIComponent(param.name)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  const search = query.length ? `?${query.join('&')}` : '';
+  return { pathStr: pathStr + search };
+}
+
+function exampleValueFor(param) {
+  if (param.example !== undefined) return param.example;
+  const schema = param.schema || {};
+  if (schema.example !== undefined) return schema.example;
+  if (schema.default !== undefined) return schema.default;
+  if (Array.isArray(schema.enum) && schema.enum.length) return schema.enum[0];
+  return undefined;
+}
+
+module.exports = { listCheckableEndpoints, buildRequest };

package/src/spec.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('fs');
+const https = require('https');
+const http = require('http');
+
+function fetchText(url) {
+  const client = url.startsWith('https:') ? https : http;
+  return new Promise((resolve, reject) => {
+    client
+      .get(url, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          fetchText(res.headers.location).then(resolve, reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`GET ${url} -> HTTP ${res.statusCode}`));
+          res.resume();
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (body += chunk));
+        res.on('end', () => resolve(body));
+      })
+      .on('error', reject);
+  });
+}
+
+async function loadSpec(specPathOrUrl) {
+  let raw;
+  if (/^https?:\/\//i.test(specPathOrUrl)) {
+    raw = await fetchText(specPathOrUrl);
+  } else {
+    raw = fs.readFileSync(specPathOrUrl, 'utf8');
+  }
+  let spec;
+  try {
+    spec = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Could not parse "${specPathOrUrl}" as JSON. specdrift v0.1 reads OpenAPI JSON specs only ` +
+        `(YAML support is a known gap, not silently ignored -- see README). Parse error: ${err.message}`
+    );
+  }
+  if (!spec.openapi || !String(spec.openapi).startsWith('3.')) {
+    throw new Error(
+      `"${specPathOrUrl}" does not look like an OpenAPI 3.x document (missing/unsupported "openapi" field). ` +
+        'specdrift v0.1 supports OpenAPI 3.x only.'
+    );
+  }
+  return spec;
+}
+
+function resolveRef(spec, ref) {
+  if (typeof ref !== 'string' || !ref.startsWith('#/')) {
+    throw new Error(`Unsupported $ref (only local refs starting with "#/" are supported): ${ref}`);
+  }
+  const parts = ref.slice(2).split('/');
+  let node = spec;
+  for (const part of parts) {
+    if (node == null || !(part in node)) {
+      throw new Error(`Could not resolve $ref "${ref}" in spec`);
+    }
+    node = node[part];
+  }
+  return node;
+}
+
+function resolveSchema(spec, schema, seen = new Set()) {
+  if (schema && typeof schema === 'object' && schema.$ref) {
+    if (seen.has(schema.$ref)) {
+      return {};
+    }
+    seen.add(schema.$ref);
+    return resolveSchema(spec, resolveRef(spec, schema.$ref), seen);
+  }
+  return schema;
+}
+
+module.exports = { loadSpec, resolveRef, resolveSchema, fetchText };

package/test/fixtures/openapi.json

@@ -0,0 +1,60 @@
+{
+  "openapi": "3.0.3",
+  "info": { "title": "Fixture API", "version": "1.0.0" },
+  "paths": {
+    "/widgets": {
+      "get": {
+        "operationId": "listWidgets",
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": { "$ref": "#/components/schemas/Widget" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/widgets/{id}": {
+      "get": {
+        "operationId": "getWidget",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "example": "w1" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "ok",
+            "content": {
+              "application/json": { "schema": { "$ref": "#/components/schemas/Widget" } }
+            }
+          },
+          "404": { "description": "not found" }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Widget": {
+        "type": "object",
+        "required": ["id", "name", "price"],
+        "properties": {
+          "id": { "type": "string" },
+          "name": { "type": "string" },
+          "price": { "type": "number" },
+          "inStock": { "type": "boolean" }
+        }
+      }
+    }
+  }
+}

package/test/fixtures/server.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// Deterministic fixture server used to verify specdrift's drift detection
+// end-to-end before publishing, the same way d1-migration-guard was verified
+// against planted-good and planted-bad fixtures before its repo went public.
+const http = require('http');
+
+const mode = process.argv[2] || 'clean';
+const port = Number(process.argv[3] || 4123);
+
+function send(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://localhost:${port}`);
+
+  if (url.pathname === '/widgets') {
+    if (mode === 'clean') {
+      return send(res, 200, [{ id: 'w1', name: 'Widget One', price: 9.99, inStock: true }]);
+    }
+    // drift: missing required "price", extra undeclared "sku"
+    return send(res, 200, [{ id: 'w1', name: 'Widget One', sku: 'SKU-1' }]);
+  }
+
+  if (url.pathname === '/widgets/w1') {
+    if (mode === 'clean') {
+      return send(res, 200, { id: 'w1', name: 'Widget One', price: 9.99, inStock: true });
+    }
+    // drift: price is now a string ("9.99") instead of a number, and status is
+    // 500 which the spec never declares for this operation
+    return send(res, 500, { id: 'w1', name: 'Widget One', price: '9.99' });
+  }
+
+  send(res, 404, { error: 'not found' });
+});
+
+server.listen(port, () => {
+  console.log(`fixture server (${mode}) listening on http://localhost:${port}`);
+});