contract-drift-detection 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +89 -162
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  All notable changes to this project are documented in this file.
4
4
 
5
+ ## 0.1.4 - 2026-03-16
6
+
7
+ ### Improved
8
+
9
+ - Reworked README for npm users with clearer onboarding and prerequisites.
10
+ - Added explicit first-run flows for `quickstart`, `--spec`, `--discover`, and `--spec-url`.
11
+ - Expanded troubleshooting section with actionable recovery steps.
12
+ - Clarified CLI usage, runtime diagnostics endpoints, and CORS guidance.
13
+
5
14
  ## 0.1.3 - 2026-03-16
6
15
 
7
16
  ### Improved
package/README.md CHANGED
@@ -1,172 +1,111 @@
1
1
  # Contract Drift Detection
2
2
 
3
- Contract Drift Detection is a stateful OpenAPI mock server with proxy-based response validation.
3
+ Contract Drift Detection is a developer CLI that gives you a stateful mock API from OpenAPI and detects contract drift against real backend responses.
4
4
 
5
- It solves the frontend/backend integration gap by combining:
5
+ Use it when:
6
6
 
7
- 1. **Spec-first mocking** (OpenAPI 3.x)
8
- 2. **Persistent local API state** (CRUD that actually mutates)
9
- 3. **Live contract drift detection** against real backend responses
7
+ - frontend is blocked by incomplete backend endpoints,
8
+ - your team has an OpenAPI contract but real responses drift from it,
9
+ - you want one local endpoint that supports mock mode and proxy mode.
10
10
 
11
- 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.
11
+ ## What this tool does
12
12
 
13
- ## What problem this resolves
13
+ - Generates API routes from OpenAPI 3.x (`.yaml` or `.json`).
14
+ - Persists API state in a local `.mock-db.json` file.
15
+ - Supports workflow actions using OpenAPI vendor extensions (`x-mock-state`).
16
+ - In proxy mode, forwards traffic to real backend and validates responses against your spec.
17
+ - Prints visible drift alerts when schema mismatches happen.
14
18
 
15
- Frontend and backend teams usually have to choose between two incomplete options:
19
+ ## What you need before starting
16
20
 
17
- - Stateless OpenAPI mockers that validate contracts but do not persist mutations.
18
- - Fake JSON backends that persist state but know nothing about the OpenAPI spec the frontend was actually built against.
21
+ - Node.js `>= 20`
22
+ - One of these:
23
+ - local OpenAPI file (`openapi.yaml` / `openapi.json`), or
24
+ - backend URL that exposes OpenAPI, or
25
+ - nothing (use `quickstart` to generate starter contract)
19
26
 
20
- This project combines both and adds a third layer: drift detection against a live backend.
27
+ ## Fastest way to start
21
28
 
22
- ### Typical outcomes
23
-
24
- - Frontend can develop end-to-end before backend is complete.
25
- - Backend drift is detected immediately in development, not in QA/production.
26
- - Teams converge faster on a stable API contract.
27
-
28
- ## Features
29
-
30
- - Generates Fastify routes directly from an OpenAPI 3.x file.
31
- - Persists state in a local JSON file so POST, PATCH, and DELETE affect future requests.
32
- - Seeds collections from component schemas using realistic sample data.
33
- - Supports action-style workflows with `x-mock-state` vendor extensions instead of a separate DSL.
34
- - Proxies to a live backend with `--drift-check` and validates real responses against the contract.
35
- - Ships as a CLI and as a reusable library.
36
-
37
- ## Install and run
38
-
39
- ### Use directly with `npx` (no install)
40
-
41
- ```bash
42
- npx contract-drift-detection@latest --spec ./openapi.yaml --port 4010
43
- ```
44
-
45
- (`serve` subcommand is optional; root command accepts serve options.)
46
-
47
- ### Install globally
48
-
49
- ```bash
50
- npm i -g contract-drift-detection
51
- cdd --help
52
- ```
53
-
54
- ### Install in a project
55
-
56
- ```bash
57
- npm install
58
- npm run build
59
- ```
60
-
61
- For local development:
62
-
63
- ```bash
64
- npm run dev
65
- ```
66
-
67
- ## 30-second quick start
68
-
69
- No spec file yet? Start instantly:
29
+ ### Option A: no spec yet (recommended first run)
70
30
 
71
31
  ```bash
72
32
  npx contract-drift-detection@latest quickstart
73
33
  ```
74
34
 
75
- Already have an OpenAPI file? Start with local spec:
35
+ This creates a starter OpenAPI file and starts the server immediately.
76
36
 
77
- ```bash
78
- npx contract-drift-detection@latest serve --spec ./openapi.yaml --port 4010
79
- ```
80
-
81
- Create a starter config + starter OpenAPI file in current directory:
37
+ ### Option B: you already have a local spec
82
38
 
83
39
  ```bash
84
- npx contract-drift-detection@latest init
85
- ```
86
-
87
- If your backend already exposes OpenAPI, avoid writing spec manually:
88
-
89
- ```bash
90
- npx contract-drift-detection@latest serve --discover http://localhost:8080 --port 4010
40
+ npx contract-drift-detection@latest --spec ./openapi.yaml --port 4010
91
41
  ```
92
42
 
93
- Or use direct remote spec URL:
43
+ ### Option C: backend exposes OpenAPI
94
44
 
95
45
  ```bash
96
- npx contract-drift-detection@latest serve --spec-url http://localhost:8080/openapi.json --port 4010
46
+ npx contract-drift-detection@latest --discover http://localhost:8080 --port 4010
97
47
  ```
98
48
 
99
- If `--discover` fails, your backend likely does not expose OpenAPI at common paths.
100
- Try either:
49
+ If discover still fails, use explicit endpoint:
101
50
 
102
51
  ```bash
103
- npx contract-drift-detection@latest serve --spec-url http://localhost:8080/v3/api-docs --port 4010
52
+ npx contract-drift-detection@latest --spec-url http://localhost:8080/v3/api-docs --port 4010
104
53
  ```
105
54
 
106
- or bootstrap instantly:
55
+ ## Typical frontend + backend integration flow
107
56
 
108
- ```bash
109
- npx contract-drift-detection@latest quickstart
110
- ```
57
+ 1. Start backend (optional for mock-only mode).
58
+ 2. Start this tool on `http://localhost:4010`.
59
+ 3. Point frontend API base URL to `http://localhost:4010`.
60
+ 4. Use mock mode during backend gaps.
61
+ 5. Turn on drift-check mode when backend is available.
111
62
 
112
- Start in drift detection mode against a real backend:
63
+ Drift-check example:
113
64
 
114
65
  ```bash
115
- npx contract-drift-detection@latest serve \
66
+ npx contract-drift-detection@latest \
116
67
  --discover http://localhost:8080 \
117
- --port 4010 \
118
- --drift-check http://localhost:8080
68
+ --drift-check http://localhost:8080 \
69
+ --port 4010
119
70
  ```
120
71
 
121
- If the backend is flaky and you still want local progress, add `--fallback-to-mock`.
72
+ ## CLI usage
122
73
 
123
- Point your frontend API base URL to `http://localhost:4010`.
124
-
125
- ## CLI
74
+ `serve` subcommand is optional. Root command accepts serve options directly.
126
75
 
127
76
  ```text
128
- contract-drift-detection serve [--spec <path> | --spec-url <url> | --discover <backend-url>] [--port 4010] [--host 0.0.0.0] [--db .mock-db.json] [--cors-origin *] [--drift-check <url>] [--fallback-to-mock] [--verbose]
77
+ contract-drift-detection [--spec <path> | --spec-url <url> | --discover <backend-url>] [--port 4010] [--host 0.0.0.0] [--db .mock-db.json] [--cors-origin *] [--drift-check <url>] [--fallback-to-mock] [--verbose]
78
+ contract-drift-detection serve [same options as above]
129
79
  contract-drift-detection init [--spec openapi.yaml] [--template rest-crud|none] [--db .mock-db.json] [--port 4010] [--host 0.0.0.0]
130
80
  contract-drift-detection quickstart [--spec openapi.yaml] [--port 4010] [--host 0.0.0.0] [--db .mock-db.json] [--cors-origin *] [--verbose]
131
-
132
- # Root command (equivalent to serve)
133
- contract-drift-detection [--spec <path> | --spec-url <url> | --discover <backend-url>] [--port 4010] ...
134
81
  ```
135
82
 
136
- `--cors-origin` defaults to `*` for frictionless browser testing.
137
-
138
- Spec resolution priority in `serve` is:
83
+ Spec resolution priority:
139
84
 
140
85
  1. `--spec`
141
86
  2. `--spec-url`
142
87
  3. `--discover`
143
88
 
144
- Remote/discovered specs are cached locally under `.cdd/`.
89
+ Remote/discovered specs are cached under `.cdd/`.
145
90
 
146
- ## Recommended workflows
91
+ ## Backend OpenAPI endpoints commonly discovered
147
92
 
148
- ### A) Frontend-first (mock only)
93
+ `--discover` checks common paths, including:
149
94
 
150
- ```bash
151
- npx cdd serve --spec ./openapi.yaml --port 4010
152
- ```
95
+ - `/openapi.json`
96
+ - `/openapi.yaml`
97
+ - `/api/openapi.json`
98
+ - `/api/openapi.yaml`
99
+ - `/swagger.json`
100
+ - `/swagger/v1/swagger.json`
101
+ - `/v3/api-docs`
102
+ - `/api-docs-json`
103
+ - `/api-docs`
104
+ - `/docs/openapi.json`
153
105
 
154
- Use this when backend endpoints are not ready.
106
+ ## OpenAPI workflow actions (`x-mock-state`)
155
107
 
156
- ### B) Integration mode (proxy + drift detection)
157
-
158
- ```bash
159
- npx cdd serve \
160
- --spec ./openapi.yaml \
161
- --port 4010 \
162
- --drift-check http://localhost:8080
163
- ```
164
-
165
- Use this when backend is partially/fully available and you want immediate contract mismatch alerts.
166
-
167
- ## OpenAPI workflow actions
168
-
169
- Instead of inventing a separate configuration language, action endpoints are defined directly in the OpenAPI document with vendor extensions.
108
+ Example:
170
109
 
171
110
  ```yaml
172
111
  paths:
@@ -188,70 +127,58 @@ Supported actions:
188
127
  - `replace`
189
128
  - `append`
190
129
 
191
- Values inside `assign` and `set` can reference request input with `{{body.field}}`, `{{params.id}}`, `{{query.key}}`, and `{{headers.header_name}}`.
130
+ Template values are supported in `assign` and `set`, for example:
192
131
 
193
- ## Runtime endpoints
132
+ - `{{body.field}}`
133
+ - `{{params.id}}`
134
+ - `{{query.key}}`
135
+ - `{{headers.authorization}}`
194
136
 
195
- - `GET /__health` returns a simple health payload.
196
- - `GET /__spec` returns the dereferenced OpenAPI document currently in memory.
197
- - `GET /__routes` returns generated route diagnostics (method/path/operation).
137
+ ## Runtime diagnostic endpoints
198
138
 
199
- ## Browser/CORS notes
139
+ - `GET /__health` → health check
140
+ - `GET /__spec` → resolved OpenAPI in memory
141
+ - `GET /__routes` → generated route summary
200
142
 
201
- - Default CORS is enabled for all origins (`*`) so local frontend apps can call the mock server immediately.
202
- - For stricter setups, set a specific origin:
143
+ ## CORS notes
144
+
145
+ - Default CORS is enabled for all origins (`*`) for fast local onboarding.
146
+ - For stricter browser setup:
203
147
 
204
148
  ```bash
205
- npx cdd serve --spec ./openapi.yaml --cors-origin http://localhost:5173
149
+ npx contract-drift-detection@latest --spec ./openapi.yaml --cors-origin http://localhost:5173
206
150
  ```
207
151
 
208
- - If you see `EADDRINUSE`, choose a different port (`--port 4020`) or stop the process already using that port.
152
+ ## Troubleshooting
153
+
154
+ ### `Could not discover an OpenAPI spec ...`
209
155
 
210
- ## Example product workflow
156
+ - Try explicit endpoint with `--spec-url`.
157
+ - Or use `quickstart` if backend does not expose OpenAPI.
158
+ - Or run `init` to scaffold starter files.
211
159
 
212
- 1. Start the mock server from the OpenAPI spec before the backend is ready.
213
- 2. Build the frontend against persistent local state instead of hand-written fixtures.
214
- 3. Switch on `--drift-check` when backend endpoints start coming online.
215
- 4. Keep frontend traffic pointed at this tool until contract mismatches are resolved.
160
+ ### `EADDRINUSE: address already in use`
216
161
 
217
- ## Development
162
+ - Port already taken. Choose another port:
218
163
 
219
164
  ```bash
220
- npm run typecheck
221
- npm test
222
- npm run lint
223
- npm run build
165
+ npx contract-drift-detection@latest --spec ./openapi.yaml --port 4020
224
166
  ```
225
167
 
226
- ## Release verification
168
+ ### Need full stack traces for debugging
227
169
 
228
170
  ```bash
229
- npm run release:verify
171
+ CDD_SHOW_STACK=1 npx contract-drift-detection@latest --spec ./openapi.yaml
230
172
  ```
231
173
 
232
- This runs typecheck, tests, lint, build, and `npm pack --dry-run`.
233
-
234
- ## Real frontend + backend test
235
-
236
- Use the built-in demo harness to validate this package in a full request chain:
237
-
238
- 1. `npm run demo:backend`
239
- 2. `npm run demo:mock:drift`
240
- 3. `npm run demo:frontend`
241
-
242
- Then open `http://localhost:5173` and exercise requests through the browser.
243
-
244
- For the complete flow and drift simulation, see `docs/REAL_STACK_TEST.md`.
245
-
246
- ## Launch
247
-
248
- For release automation and go-to-market steps, follow:
174
+ ## Package and binaries
249
175
 
250
- - `docs/RELEASE.md` for versioning and npm publish
251
- - `docs/LAUNCH_CHECKLIST.md` for launch channels and success metrics
176
+ - npm package: `contract-drift-detection`
177
+ - binaries: `contract-drift-detection`, `cdd`
178
+ - license: MIT
252
179
 
253
- ## Shipping notes
180
+ ## Links
254
181
 
255
- - The package exposes the `cdd` and `contract-drift-detection` binaries.
256
- - `prepublishOnly` runs typecheck, tests, and build to block broken releases.
257
- - The included example spec under `examples/` is intended for demos, screenshots, and onboarding.
182
+ - Changelog: `CHANGELOG.md`
183
+ - Release process: `docs/RELEASE.md`
184
+ - Real stack demo test flow: `docs/REAL_STACK_TEST.md`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "contract-drift-detection",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "Stateful OpenAPI mock server with contract drift detection",
5
5
  "repository": {
6
6
  "type": "git",