contract-drift-detection 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,211 @@
+# Contract Drift Detection
+
+Contract Drift Detection is a stateful OpenAPI mock server with proxy-based response validation.
+
+It solves the frontend/backend integration gap by combining:
+
+1. **Spec-first mocking** (OpenAPI 3.x)
+2. **Persistent local API state** (CRUD that actually mutates)
+3. **Live contract drift detection** against real backend responses
+
+If your frontend is blocked by backend readiness, or your backend keeps returning payloads that quietly break UI assumptions, this package is built for that exact pain.
+
+## What problem this resolves
+
+Frontend and backend teams usually have to choose between two incomplete options:
+
+- Stateless OpenAPI mockers that validate contracts but do not persist mutations.
+- Fake JSON backends that persist state but know nothing about the OpenAPI spec the frontend was actually built against.
+
+This project combines both and adds a third layer: drift detection against a live backend.
+
+### Typical outcomes
+
+- Frontend can develop end-to-end before backend is complete.
+- Backend drift is detected immediately in development, not in QA/production.
+- Teams converge faster on a stable API contract.
+
+## Features
+
+- Generates Fastify routes directly from an OpenAPI 3.x file.
+- Persists state in a local JSON file so POST, PATCH, and DELETE affect future requests.
+- Seeds collections from component schemas using realistic sample data.
+- Supports action-style workflows with `x-mock-state` vendor extensions instead of a separate DSL.
+- Proxies to a live backend with `--drift-check` and validates real responses against the contract.
+- Ships as a CLI and as a reusable library.
+
+## Install and run
+
+### Use directly with `npx` (no install)
+
+```bash
+npx contract-drift-detection@latest serve --spec ./openapi.yaml --port 4010
+```
+
+### Install globally
+
+```bash
+npm i -g contract-drift-detection
+cdd --help
+```
+
+### Install in a project
+
+```bash
+npm install
+npm run build
+```
+
+For local development:
+
+```bash
+npm run dev
+```
+
+## 30-second quick start
+
+Run the included example API:
+
+```bash
+npx tsx src/cli.ts serve --spec ./examples/helpdesk.openapi.yaml --port 4010
+```
+
+Create a starter config file in any project:
+
+```bash
+npx tsx src/cli.ts init
+```
+
+Start in drift detection mode against a real backend:
+
+```bash
+npx tsx src/cli.ts serve \
+  --spec ./examples/helpdesk.openapi.yaml \
+  --port 4010 \
+  --drift-check http://localhost:8080
+```
+
+If the backend is flaky and you still want local progress, add `--fallback-to-mock`.
+
+Point your frontend API base URL to `http://localhost:4010`.
+
+## CLI
+
+```text
+contract-drift-detection serve --spec <path> [--port 4010] [--host 0.0.0.0] [--db .mock-db.json] [--cors-origin *] [--drift-check <url>] [--fallback-to-mock] [--verbose]
+contract-drift-detection init [--spec openapi.yaml] [--db .mock-db.json] [--port 4010] [--host 0.0.0.0]
+```
+
+`--cors-origin` defaults to `*` for frictionless browser testing.
+
+## Recommended workflows
+
+### A) Frontend-first (mock only)
+
+```bash
+npx cdd serve --spec ./openapi.yaml --port 4010
+```
+
+Use this when backend endpoints are not ready.
+
+### B) Integration mode (proxy + drift detection)
+
+```bash
+npx cdd serve \
+  --spec ./openapi.yaml \
+  --port 4010 \
+  --drift-check http://localhost:8080
+```
+
+Use this when backend is partially/fully available and you want immediate contract mismatch alerts.
+
+## OpenAPI workflow actions
+
+Instead of inventing a separate configuration language, action endpoints are defined directly in the OpenAPI document with vendor extensions.
+
+```yaml
+paths:
+  /tickets/{id}/resolve:
+    post:
+      x-mock-state:
+        action: update
+        target: tickets
+        find_by: id
+        set:
+          status: resolved
+```
+
+Supported actions:
+
+- `create`
+- `update`
+- `delete`
+- `replace`
+- `append`
+
+Values inside `assign` and `set` can reference request input with `{{body.field}}`, `{{params.id}}`, `{{query.key}}`, and `{{headers.header_name}}`.
+
+## Runtime endpoints
+
+- `GET /__health` returns a simple health payload.
+- `GET /__spec` returns the dereferenced OpenAPI document currently in memory.
+
+## Browser/CORS notes
+
+- Default CORS is enabled for all origins (`*`) so local frontend apps can call the mock server immediately.
+- For stricter setups, set a specific origin:
+
+```bash
+npx cdd serve --spec ./openapi.yaml --cors-origin http://localhost:5173
+```
+
+- If you see `EADDRINUSE`, choose a different port (`--port 4020`) or stop the process already using that port.
+
+## Example product workflow
+
+1. Start the mock server from the OpenAPI spec before the backend is ready.
+2. Build the frontend against persistent local state instead of hand-written fixtures.
+3. Switch on `--drift-check` when backend endpoints start coming online.
+4. Keep frontend traffic pointed at this tool until contract mismatches are resolved.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run lint
+npm run build
+```
+
+## Release verification
+
+```bash
+npm run release:verify
+```
+
+This runs typecheck, tests, lint, build, and `npm pack --dry-run`.
+
+## Real frontend + backend test
+
+Use the built-in demo harness to validate this package in a full request chain:
+
+1. `npm run demo:backend`
+2. `npm run demo:mock:drift`
+3. `npm run demo:frontend`
+
+Then open `http://localhost:5173` and exercise requests through the browser.
+
+For the complete flow and drift simulation, see `docs/REAL_STACK_TEST.md`.
+
+## Launch
+
+For release automation and go-to-market steps, follow:
+
+- `docs/RELEASE.md` for versioning and npm publish
+- `docs/LAUNCH_CHECKLIST.md` for launch channels and success metrics
+
+## Shipping notes
+
+- The package exposes the `cdd` and `contract-drift-detection` binaries.
+- `prepublishOnly` runs typecheck, tests, and build to block broken releases.
+- The included example spec under `examples/` is intended for demos, screenshots, and onboarding.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }