x-openapi-flow 1.3.6 → 1.4.0

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 (6) hide show
  1. package/README.md +343 -306
  2. package/adapters/collections/insomnia-adapter.js +211 -15
  3. package/adapters/collections/postman-adapter.js +195 -15
  4. package/adapters/ui/redoc/x-openapi-flow-redoc-plugin.js +620 -91
  5. package/adapters/ui/redoc-adapter.js +132 -5
  6. package/package.json +4 -2
package/README.md CHANGED
@@ -1,435 +1,472 @@
1
- # x-openapi-flow
1
+ <!-- Auto-generated from /README.md via scripts/sync-package-readme.js. Do not edit directly. -->
2
2
 
3
3
  ![x-openapi-flow logo](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-logo.svg)
4
4
 
5
- CLI and extension contract for documenting and validating resource lifecycle workflows in OpenAPI using `x-openapi-flow`.
5
+ [![npm version](https://img.shields.io/npm/v/x-openapi-flow?label=npm%20version)](https://www.npmjs.com/package/x-openapi-flow)
6
+ [![npm downloads](https://img.shields.io/npm/dm/x-openapi-flow?label=npm%20downloads)](https://www.npmjs.com/package/x-openapi-flow)
7
+ ![node](https://img.shields.io/badge/node-%3E%3D18-339933)
8
+ ![license](https://img.shields.io/npm/l/x-openapi-flow)
9
+ [![CI](https://github.com/tiago-marques/x-openapi-flow/actions/workflows/x-openapi-flow-validate.yml/badge.svg)](https://github.com/tiago-marques/x-openapi-flow/actions/workflows/x-openapi-flow-validate.yml)
10
+ [![open issues](https://img.shields.io/github/issues/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/issues)
11
+ [![last commit](https://img.shields.io/github/last-commit/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/commits/main)
12
+ ![copilot ready](https://img.shields.io/badge/Copilot-Ready-00BFA5?logo=githubcopilot&logoColor=white)
6
13
 
7
- ## Overview
14
+ # OpenAPI describes APIs.
15
+ # x-openapi-flow describes how they actually work — for developers and AI.
8
16
 
9
- `x-openapi-flow` validates:
17
+ `x-openapi-flow` is an OpenAPI vendor extension and CLI for documenting and validating resource lifecycle workflows.
18
+ It adds explicit state-machine metadata (`x-openapi-flow`) to operations and validates both schema and lifecycle graph consistency.
10
19
 
11
- - Extension schema correctness
12
- - Lifecycle graph consistency
13
- - Optional quality checks for transitions and references
20
+ ---
14
21
 
15
- It also supports a sidecar workflow (`init` + `apply`) so lifecycle metadata stays preserved when OpenAPI source files are regenerated.
22
+ ## Why This Project Matters
16
23
 
17
- ## Installation
24
+ Most teams document endpoints but not lifecycle behavior. State transitions become implicit, inconsistent, and hard to validate in CI.
25
+ `x-openapi-flow` makes flows explicit, so teams can:
18
26
 
19
- ```bash
20
- npm install x-openapi-flow
21
- ```
27
+ - Validate lifecycle consistency early in CI
28
+ - Generate flow-aware docs and diagrams
29
+ - Build SDKs that reduce invalid API calls
22
30
 
23
- Optional mirror on GitHub Packages (default usage remains unscoped on npm):
31
+ Result: faster onboarding, fewer integration regressions, and clearer contracts between API producers and consumers.
32
+
33
+ ---
34
+
35
+ ## TL;DR / Quick Start
36
+
37
+ From your API project root:
24
38
 
25
39
  ```bash
26
- npm config set @tiago-marques:registry https://npm.pkg.github.com
27
- npm install @tiago-marques/x-openapi-flow
40
+ npx x-openapi-flow init
41
+ ```
42
+ or
43
+ ```bash
44
+ npx x-openapi-flow apply openapi.x.yaml
28
45
  ```
29
46
 
30
- If authentication is required, include this in your `.npmrc`:
47
+ Default adoption path:
31
48
 
32
- ```ini
33
- //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
34
- ```
49
+ 1. Generate or update your OpenAPI source.
50
+ 2. Run `init` to create/sync sidecar flow metadata.
51
+ 3. Run `apply` whenever the OpenAPI file is regenerated.
35
52
 
36
- Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
53
+ Sidecar and output roles:
37
54
 
38
- ## Quick Start
55
+ - `{context}.x.(json|yaml)`: sidecar source of lifecycle metadata (the file you edit).
56
+ - `{context}.flow.(json|yaml)`: generated OpenAPI output after merge (the file you validate and serve in docs/tools).
57
+
58
+ Practical rule:
59
+
60
+ 1. edit `.x`
61
+ 2. run `apply`
62
+ 3. validate/use `.flow`
63
+
64
+ Full rollout guide: [docs/wiki/getting-started/Adoption-Playbook.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/getting-started/Adoption-Playbook.md)
65
+ Troubleshooting: [docs/wiki/reference/Troubleshooting.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Troubleshooting.md)
66
+
67
+ ---
68
+
69
+
70
+ 1. Bootstrap once per project.
39
71
 
40
72
  ```bash
41
73
  npx x-openapi-flow init
42
- npx x-openapi-flow apply openapi.yaml
43
74
  ```
44
75
 
45
- Optional checks:
76
+ 2. Re-apply sidecar metadata after each OpenAPI regeneration.
46
77
 
47
78
  ```bash
48
- npx x-openapi-flow validate openapi.yaml --profile strict
49
- npx x-openapi-flow lint openapi.yaml
50
- npx x-openapi-flow graph openapi.yaml
79
+ npx x-openapi-flow apply openapi.yaml
51
80
  ```
52
81
 
53
- ## CLI Commands
54
-
55
82
  ```bash
56
- npx x-openapi-flow help [command]
57
- npx x-openapi-flow --help
58
- npx x-openapi-flow version
59
- npx x-openapi-flow --version
60
- npx x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
61
- npx x-openapi-flow init [--flows path] [--force] [--dry-run]
62
- npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
63
- npx x-openapi-flow diff [openapi-file] [--flows path] [--format pretty|json]
64
- npx x-openapi-flow lint [openapi-file] [--format pretty|json] [--config path]
65
- npx x-openapi-flow analyze [openapi-file] [--format pretty|json] [--out path] [--merge] [--flows path]
66
- npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
67
- npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
68
- npx x-openapi-flow generate-postman [openapi-file] [--output path] [--with-scripts]
69
- npx x-openapi-flow generate-insomnia [openapi-file] [--output path]
70
- npx x-openapi-flow generate-redoc [openapi-file] [--output path]
71
- npx x-openapi-flow graph <openapi-file> [--format mermaid|json]
72
- npx x-openapi-flow doctor [--config path]
73
- npx x-openapi-flow completion [bash|zsh]
83
+ npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
74
84
  ```
75
85
 
76
- Helpful additions:
86
+ 4. Optional diagnostics for review and troubleshooting.
77
87
 
78
- - Command-specific help: `x-openapi-flow <command> --help` (example: `x-openapi-flow validate --help`)
79
- - Verbose troubleshooting: `x-openapi-flow <command> --verbose`
80
- - Shell completion output: `x-openapi-flow completion bash` or `x-openapi-flow completion zsh`
88
+ ```bash
89
+ npx x-openapi-flow diff openapi.yaml --format pretty
90
+ npx x-openapi-flow lint openapi.flow.yaml
91
+ npx x-openapi-flow graph openapi.flow.yaml --format mermaid
92
+ ```
93
+
94
+ What this gives your team in practice:
81
95
 
82
- ## Output Adapters
96
+ - deterministic lifecycle checks in local dev and CI
97
+ - explicit transition contracts instead of implicit tribal knowledge
98
+ - safer API evolution with fewer integration regressions
83
99
 
84
- `x-openapi-flow` now supports modular output adapters that reuse the same internal flow graph:
100
+ ## Integration Experience (What You See)
85
101
 
86
- - OpenAPI + `x-openapi-flow` -> parser -> graph builder -> adapters
87
- - Adapters: docs (`export-doc-flows`), SDK (`generate-sdk`), Postman (`generate-postman`), Insomnia (`generate-insomnia`)
88
- and Redoc package (`generate-redoc`)
102
+ ### Swagger UI
89
103
 
90
- ### Redoc/Docs Adapter (`export-doc-flows`)
104
+ Use this when you want interactive docs with lifecycle context on each operation.
91
105
 
92
106
  ```bash
93
- npx x-openapi-flow export-doc-flows openapi.yaml --output ./docs/api-flows.md
94
- npx x-openapi-flow export-doc-flows openapi.yaml --format json --output ./docs/api-flows.json
107
+ cd example/swagger-ui
108
+ npm install
109
+ npm run apply
110
+ npm start
95
111
  ```
96
112
 
97
- Generates a lifecycle page (or JSON model) with:
113
+ Note: in this example, `npm run apply` prefers local sidecars (`swagger.x.yaml|yml|json`) and falls back to `examples/swagger.x.yaml|json` when a local sidecar is not present.
114
+
115
+ Experience outcome:
116
+
117
+ - operation docs enriched with `x-openapi-flow` fields
118
+ - visual lifecycle context while navigating endpoints
119
+
120
+ Demo media:
121
+
122
+ ![Swagger UI Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/swagger-ui-flow-lifecycle.png)
123
+ ![Swagger UI Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/swagger-ui-flow-lifecycle-2.png)
98
124
 
99
- - Flow/Lifecycle panel per resource
100
- - Mermaid diagram per resource
101
- - Current state, prerequisites (`prerequisite_operation_ids`), next operations (`next_operation_id`)
125
+ ### Redoc
102
126
 
103
- ### Redoc Package Adapter (`generate-redoc`)
127
+ Use this when you want a static docs bundle to share internally or publish.
104
128
 
105
129
  ```bash
106
- npx x-openapi-flow generate-redoc openapi.yaml --output ./redoc-flow
130
+ cd example/redoc
131
+ npm install
132
+ npm run apply
133
+ npm run generate
107
134
  ```
108
135
 
109
- Generates a ready-to-open Redoc bundle with:
136
+ Experience outcome:
110
137
 
111
- - `index.html` (Redoc + Flow/Lifecycle panel)
112
- - `x-openapi-flow-redoc-plugin.js` (DOM enhancer)
113
- - `flow-model.json` (flow graph model)
114
- - copied OpenAPI spec (`openapi.yaml`/`openapi.json`)
138
+ - portable `redoc-flow/` package with lifecycle panel
139
+ - stable documentation artifact for teams and portals
115
140
 
116
- ### Postman Adapter (`generate-postman`)
141
+ Demo media:
142
+
143
+ ![Redoc Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle.png)
144
+ ![Redoc Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle-2.png)
145
+ ![Redoc Flow Lifecycle 3](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/redoc-flow-lifecycle-3.png)
146
+
147
+ ### Postman
148
+
149
+ Use this when you want collections aligned with lifecycle transitions.
117
150
 
118
151
  ```bash
119
- npx x-openapi-flow generate-postman openapi.yaml --output ./x-openapi-flow.postman_collection.json --with-scripts
152
+ cd example/postman
153
+ npm install
154
+ npm run apply
155
+ npm run generate
120
156
  ```
121
157
 
122
- Generates lifecycle-oriented folders/journeys and optional scripts for:
158
+ Experience outcome:
159
+
160
+ - flow-oriented Postman collection
161
+ - request execution closer to real transition paths
123
162
 
124
- - prerequisite enforcement before request execution
125
- - propagated operation tracking and ID persistence in collection variables
163
+ Demo media:
126
164
 
127
- ### Insomnia Adapter (`generate-insomnia`)
165
+ ![Postman Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/postman-flow-lifecycle.png)
166
+ ![Postman Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/postman-flow-lifecycle-2.png)
167
+
168
+ ### Insomnia
169
+
170
+ Use this when your team runs API scenarios in Insomnia workspaces.
128
171
 
129
172
  ```bash
130
- npx x-openapi-flow generate-insomnia openapi.yaml --output ./x-openapi-flow.insomnia.json
173
+ cd example/insomnia
174
+ npm install
175
+ npm run apply
176
+ npm run generate
131
177
  ```
132
178
 
133
- Generates an Insomnia export organized by resource flow groups and ordered requests.
179
+ Experience outcome:
180
+
181
+ - generated workspace export with grouped lifecycle requests
182
+ - faster onboarding to operation prerequisites and flow order
183
+
184
+ Demo media:
134
185
 
135
- ## SDK Generator (`generate-sdk`)
186
+ ![Insomnia Flow Lifecycle 1](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/insomnia-flow-lifecycle.png)
187
+ ![Insomnia Flow Lifecycle 2](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/insomnia-flow-lifecycle-2.png)
136
188
 
137
- Generate a flow-aware SDK from OpenAPI + `x-openapi-flow` metadata.
189
+ ### SDK (TypeScript)
190
+
191
+ Use this when you want a generated flow-aware SDK for application integration.
138
192
 
139
193
  ```bash
140
- npx x-openapi-flow generate-sdk openapi.yaml --lang typescript --output ./sdk
194
+ cd example/sdk/typescript
195
+ npm install
196
+ npm run apply
197
+ npm run generate
198
+ npm run run:sample
141
199
  ```
142
200
 
143
- MVP output (TypeScript):
201
+ Experience outcome:
202
+
203
+ - generated TypeScript SDK in `sdk/` from `x-openapi-flow` metadata
204
+ - minimal runnable sample showing typed SDK usage in `src/sample.ts`
205
+ - lifecycle-oriented methods and transition-aware resource instances
144
206
 
145
- - `src/resources/<Resource>.ts`: resource client + state classes (`PaymentAuthorized`, `PaymentCaptured`, etc.)
146
- - `src/index.ts`: root `FlowApiClient`
147
- - `src/http-client.ts`: pluggable HTTP client interface and fetch implementation
148
- - `src/flow-helpers.ts`: `runFlow("authorize -> capture")`
149
- - `flow-model.json`: intermediate model `{ resource, operations, prerequisites, nextOperations, states }`
207
+ Example project:
150
208
 
151
- SDK layers (resource-centric):
209
+ - [example/sdk/typescript/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/example/sdk/typescript/README.md)
152
210
 
153
- - Collection/service layer: `api.payments.create()`, `api.payments.retrieve(id)`, `api.payments.list()`
154
- - Resource instance/state layer: objects expose valid lifecycle transitions (`payment.capture()`, etc.)
155
- - Optional lifecycle helper methods at service level (`api.payments.capture(id, params, { autoPrerequisites: true })`)
211
+ More integration details:
156
212
 
157
- Pipeline used by the generator:
213
+ - [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)
214
+ - [docs/wiki/integrations/Redoc-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Redoc-Integration.md)
215
+ - [docs/wiki/integrations/Postman-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Postman-Integration.md)
216
+ - [docs/wiki/integrations/Insomnia-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Insomnia-Integration.md)
158
217
 
159
- - OpenAPI -> parser -> flow graph -> state machine -> templates -> SDK
160
- - Reuses lifecycle graph logic from the validator to stay consistent with `validate`, `graph`, and `diff`
161
- - Transition ordering uses `next_operation_id`, `prerequisite_operation_ids`, and state transitions from `x-openapi-flow`
218
+ ---
162
219
 
163
- ## Flow Analyzer (`analyze`)
220
+ ## CLI in Practice (Server Workflow)
164
221
 
165
- Use `analyze` to bootstrap a sidecar from OpenAPI paths/operation names.
222
+ Use this sequence as your default lifecycle guardrail in backend projects:
166
223
 
167
224
  ```bash
168
- npx x-openapi-flow analyze openapi.yaml --out openapi.x.yaml
169
- npx x-openapi-flow analyze openapi.yaml --format json
170
- npx x-openapi-flow analyze openapi.yaml --merge --flows openapi.x.yaml
225
+ # 1) Bootstrap sidecar from OpenAPI source
226
+ npx x-openapi-flow init
227
+
228
+ # 2) Merge sidecar into flow-aware OpenAPI output
229
+ npx x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
230
+
231
+ # 3) Detect drift before commit
232
+ npx x-openapi-flow diff openapi.yaml --format pretty
233
+
234
+ # 4) Enforce lifecycle quality gates
235
+ npx x-openapi-flow validate openapi.flow.yaml --profile strict --strict-quality
236
+ npx x-openapi-flow lint openapi.flow.yaml
237
+
238
+ # 5) Generate graph artifact for PR discussion
239
+ npx x-openapi-flow graph openapi.flow.yaml --format mermaid
171
240
  ```
172
241
 
173
- Notes:
174
-
175
- - The output is heuristic and intended as a starting point.
176
- - Inferred states/transitions should be reviewed and adjusted by API/domain owners.
177
- - Default output format is `pretty`; without `--out`, the suggested sidecar is printed to stdout.
178
- - `--merge` merges inferred data into an existing sidecar (default path or `--flows`) while preserving existing operation fields.
179
- - In `json`, inferred transition confidence is available in `analysis.transitionConfidence`.
180
-
181
- `diff` now reports field-level changes for operations that already exist in the sidecar.
182
- In `pretty` format, this appears under `Changed details` with changed paths per operation (for example, `current_state` or `transitions[0].target_state`).
183
- In `json` format, this appears in `diff.changedOperationDetails`:
184
-
185
- ```json
186
- {
187
- "diff": {
188
- "changedOperationDetails": [
189
- {
190
- "operationId": "listItems",
191
- "changedPaths": ["current_state"]
192
- }
193
- ]
194
- }
195
- }
242
+ CLI quick references for daily usage:
243
+
244
+ ```bash
245
+ npx x-openapi-flow help [command]
246
+ npx x-openapi-flow <command> --help
247
+ npx x-openapi-flow <command> --verbose
248
+ npx x-openapi-flow completion [bash|zsh]
196
249
  ```
197
250
 
198
- ### CI usage (`diff` as a gate)
251
+ ---
199
252
 
200
- Fail the pipeline when sidecar drift is detected:
253
+ ## SDK Generation Experience (TypeScript)
254
+
255
+ Generate a flow-aware SDK directly from your OpenAPI + `x-openapi-flow` metadata:
201
256
 
202
257
  ```bash
203
- npx x-openapi-flow diff openapi.yaml --format json | node -e '
204
- const fs = require("fs");
205
- const payload = JSON.parse(fs.readFileSync(0, "utf8"));
206
- const diff = payload.diff || {};
207
- const changes = (diff.added || 0) + (diff.removed || 0) + (diff.changed || 0);
208
- if (changes > 0) {
209
- console.error("x-openapi-flow diff detected changes. Run init/apply and commit sidecar updates.");
210
- process.exit(1);
211
- }
212
- '
258
+ npx x-openapi-flow generate-sdk openapi.flow.yaml --lang typescript --output ./sdk
213
259
  ```
214
260
 
215
- This keeps `.x` sidecar data aligned with the OpenAPI source in pull requests.
261
+ What you get:
216
262
 
217
- ## Semantic lint (`lint`)
263
+ - resource-centric classes with lifecycle-safe methods
264
+ - operation transition awareness (`next_operation_id`, prerequisites, propagated fields)
265
+ - reusable client layer for application services
218
266
 
219
- Use `lint` to run semantic checks focused on flow modeling quality.
267
+ Typical integration snippet:
220
268
 
221
- ```bash
222
- npx x-openapi-flow lint openapi.yaml
223
- npx x-openapi-flow lint openapi.yaml --format json
269
+ ```ts
270
+ import { FlowApiClient } from "./sdk/src";
271
+
272
+ const api = new FlowApiClient({ baseUrl: process.env.API_BASE_URL });
273
+
274
+ const payment = await api.payments.create({ amount: 1000 });
275
+ await payment.authorize();
276
+ await payment.capture();
224
277
  ```
225
278
 
226
- MVP semantic rules:
227
-
228
- - `next_operation_id_exists`
229
- - `prerequisite_operation_ids_exist`
230
- - `duplicate_transitions`
231
- - `terminal_path` (states without path to terminal)
232
-
233
- Disable individual rules with config (`x-openapi-flow.config.json`):
234
-
235
- ```json
236
- {
237
- "lint": {
238
- "rules": {
239
- "next_operation_id_exists": true,
240
- "prerequisite_operation_ids_exist": true,
241
- "duplicate_transitions": false,
242
- "terminal_path": true
243
- }
244
- }
245
- }
279
+ ---
280
+
281
+ ## Example: Payment Flow
282
+
283
+ ```mermaid
284
+ graph TD
285
+ CreatePayment --> AuthorizePayment
286
+ AuthorizePayment --> CapturePayment
287
+ CapturePayment --> RefundPayment
246
288
  ```
247
289
 
248
- ## Graph JSON contract (`graph --format json`)
249
-
250
- `graph --format json` returns a stable contract for CI/pipeline integrations:
251
-
252
- - `format_version`: output contract version (currently `"1.0"`).
253
- - `flowCount`: number of operations with `x-openapi-flow`.
254
- - `nodes`: sorted state names (deterministic order).
255
- - `edges`: sorted transitions by `from`, `to`, `next_operation_id`, and prerequisites.
256
- - `mermaid`: deterministic Mermaid rendering of the same graph.
257
-
258
- Example:
259
-
260
- ```json
261
- {
262
- "format_version": "1.0",
263
- "flowCount": 3,
264
- "nodes": ["CONFIRMED", "CREATED", "SHIPPED"],
265
- "edges": [
266
- {
267
- "from": "CONFIRMED",
268
- "to": "SHIPPED",
269
- "next_operation_id": "shipOrder",
270
- "prerequisite_operation_ids": []
271
- }
272
- ],
273
- "mermaid": "stateDiagram-v2\n state CONFIRMED\n state CREATED\n state SHIPPED\n CONFIRMED --> SHIPPED: next:shipOrder"
274
- }
290
+ ### Flow-aware SDK Example (TypeScript)
291
+
292
+ ```ts
293
+ const payment = await sdk.payments.create({ amount: 1000 });
294
+ await payment.authorize();
295
+ await payment.capture();
296
+ await payment.refund();
275
297
  ```
276
298
 
277
- ## HTTP Methods Support
299
+ At each stage, only valid lifecycle actions should be available.
278
300
 
279
- `init`, `apply`, and `graph` support all OpenAPI 3 HTTP operation methods:
301
+ ---
280
302
 
281
- - `get`
282
- - `put`
283
- - `post`
284
- - `delete`
285
- - `options`
286
- - `head`
287
- - `patch`
288
- - `trace`
303
+ ## Installation
289
304
 
290
- ## Sidecar Workflow
305
+ Install from npm (default):
291
306
 
292
- Behavior summary:
307
+ ```bash
308
+ npm install x-openapi-flow
309
+ ```
293
310
 
294
- - `init` works on an existing OpenAPI source file in your repository.
295
- - `init` creates/synchronizes `{context}.x.(json|yaml)` as a persistent sidecar for `x-openapi-flow` data.
296
- - If `{context}.flow.(json|yaml)` does not exist, `init` generates it automatically (same merge result as `apply`).
297
- - If `{context}.flow.(json|yaml)` already exists, `init` asks in interactive mode whether to recreate it.
298
- - On confirmation (or with `--force`), `init` creates a sidecar backup as `{context}.x.(json|yaml).backup-N` before regenerating `{context}.flow.(json|yaml)`.
299
- - In non-interactive mode, `init` fails when flow output already exists unless `--force` is provided.
300
- - With `--dry-run`, `init` prints a summary of sidecar/flow behavior without writing files.
301
- - Use `apply` to inject sidecar flows back into regenerated OpenAPI source files.
302
- - If no OpenAPI/Swagger source file exists yet, generate one first with your framework's official tooling.
311
+ Optional mirror from GitHub Packages:
303
312
 
304
- ### Recommended Sequence
313
+ ```bash
314
+ npm config set @tiago-marques:registry https://npm.pkg.github.com
315
+ npm install @tiago-marques/x-openapi-flow
316
+ ```
317
+
318
+ If authentication is required, add to `.npmrc`:
319
+
320
+ ```ini
321
+ //npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
322
+ ```
323
+
324
+ Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
325
+
326
+ ---
327
+
328
+ ## CLI Reference (Selected Commands)
305
329
 
306
330
  ```bash
307
- npx x-openapi-flow init
308
- npx x-openapi-flow init --dry-run
309
- # edit {context}.x.(json|yaml)
310
- npx x-openapi-flow diff openapi.yaml
311
- npx x-openapi-flow apply openapi.yaml
331
+ npx x-openapi-flow help [command]
332
+ npx x-openapi-flow --help
333
+ npx x-openapi-flow version
334
+ npx x-openapi-flow --version
335
+ npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality]
336
+ npx x-openapi-flow init [--flows path] [--force] [--dry-run]
337
+ npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
338
+ npx x-openapi-flow analyze [openapi-file] [--format pretty|json] [--out path] [--merge] [--flows path]
339
+ npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
340
+ npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
341
+ npx x-openapi-flow generate-redoc [openapi-file] [--output path]
342
+ <!-- Demo media removed -->
343
+ npx x-openapi-flow doctor [--config path]
344
+ npx x-openapi-flow completion [bash|zsh]
345
+ ```
346
+
347
+ Global flag for troubleshooting:
348
+
349
+ ```bash
350
+ npx x-openapi-flow <command> --verbose
312
351
  ```
313
352
 
314
- ## Sidecar File Contract (all supported fields)
315
-
316
- Sidecar top-level shape:
317
-
318
- ```yaml
319
- version: "1.0"
320
- operations:
321
- - operationId: createOrder
322
- x-openapi-flow:
323
- version: "1.0"
324
- id: create-order
325
- current_state: CREATED
326
- description: Creates an order and starts its lifecycle
327
- idempotency:
328
- header: Idempotency-Key
329
- required: true
330
- transitions:
331
- - target_state: PAID
332
- trigger_type: synchronous
333
- condition: Payment approved
334
- next_operation_id: payOrder
335
- prerequisite_operation_ids:
336
- - createOrder
337
- prerequisite_field_refs:
338
- - createOrder:request.body.customer_id
339
- propagated_field_refs:
340
- - createOrder:response.201.body.order_id
353
+ Full command details:
354
+
355
+ - [docs/wiki/reference/CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)
356
+ - [x-openapi-flow/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/README.md)
357
+
358
+ ---
359
+
360
+ <!-- Demo media removed -->
361
+
362
+ - Auto-detects OpenAPI source files (`openapi.yaml`, `openapi.json`, `swagger.yaml`, etc.)
363
+ - Creates or syncs `{context}.x.(json|yaml)` (sidecar with lifecycle metadata)
364
+ - Generates `{context}.flow.(json|yaml)` automatically when missing
365
+ - In interactive mode, asks before recreating existing flow files
366
+ - In non-interactive mode, requires `--force` to recreate when flow file already exists
367
+
368
+ Recommended quality gate:
369
+
370
+ ```bash
371
+ npx x-openapi-flow validate openapi.yaml --profile strict
341
372
  ```
342
373
 
343
- Top-level (sidecar document):
374
+ ---
344
375
 
345
- - `version` (optional, string): sidecar contract version. Default is `"1.0"`.
346
- - `operations` (optional, array): entries keyed by operation.
376
+ ## Validation Profiles
347
377
 
348
- Per operation entry:
378
+ - `core`: schema and orphan checks only
379
+ <!-- Demo media removed -->
380
+ - Schema contract correctness
381
+ - Orphan states
382
+ - Initial/terminal state structure
383
+ - Cycles and unreachable states
384
+ - Quality findings (duplicate transitions, invalid refs, non-terminating states)
349
385
 
350
- - `operationId` (recommended, string): target operation identifier in OpenAPI.
351
- - `x-openapi-flow` (object): lifecycle metadata for that operation.
352
- - `key` (optional, legacy): backward-compatibility fallback key used by apply.
386
+ ---
353
387
 
354
- `x-openapi-flow` fields:
388
+ ## Integrations
355
389
 
356
- - Required:
357
- - `version` (string): currently `"1.0"`.
358
- - `id` (string): unique flow id.
359
- - `current_state` (string): state represented by this operation.
360
- - Optional:
361
- - `description` (string): human-readable purpose.
362
- - `idempotency` (object):
363
- - `header` (required, string)
364
- - `required` (optional, boolean)
365
- - `transitions` (array of transition objects)
390
+ - Swagger UI: flow overview + operation-level extension panels
391
+ - Redoc: generated package with flow panel
392
+ - Postman and Insomnia: generated lifecycle-aware collections/workspaces
393
+ - SDK generator: TypeScript available, other languages planned
366
394
 
367
- Transition object fields:
395
+ <!-- Demo media removed -->
396
+ Integration docs:
368
397
 
369
- - Required:
370
- - `target_state` (string)
371
- - `trigger_type` (enum): `synchronous`, `webhook`, `polling`
372
- - Optional:
373
- - `condition` (string)
374
- - `next_operation_id` (string)
375
- - `prerequisite_operation_ids` (array of strings)
376
- - `prerequisite_field_refs` (array of strings)
377
- - `propagated_field_refs` (array of strings)
398
+ - [docs/wiki/integrations/Swagger-UI-Integration.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/integrations/Swagger-UI-Integration.md)
399
+ ---
400
+ ## Copilot Ready (AI Sidecar Authoring)
378
401
 
379
- Field refs format:
402
+ Use [llm.txt](https://github.com/tiago-marques/x-openapi-flow/blob/main/llm.txt) as authoring guidance for sidecar population.
380
403
 
381
- - `operationId:request.body.field`
382
- - `operationId:request.path.paramName`
383
- - `operationId:response.<status>.body.field`
404
+ Typical AI-assisted loop:
384
405
 
385
- ## Configuration
406
+ 1. `init`
407
+ 2. AI fills `{context}.x.(json|yaml)`
408
+ 3. `apply`
409
+ 4. `validate --profile strict`
386
410
 
387
- Create `x-openapi-flow.config.json` in your project directory:
411
+ Prompt template:
388
412
 
389
- ```json
390
- {
391
- "profile": "strict",
392
- "format": "pretty",
393
- "strictQuality": false
394
- }
413
+ ```text
414
+ Use llm.txt from this repository as authoring rules.
415
+ Populate {context}.x.(json|yaml) per operationId with coherent lifecycle states and transitions,
416
+ including next_operation_id, prerequisite_field_refs, and propagated_field_refs when applicable.
417
+ Do not change endpoint paths or HTTP methods.
395
418
  ```
396
419
 
397
- ## Compatibility
420
+ ---
398
421
 
399
- - OpenAPI input in `.yaml`, `.yml`, and `.json`
400
- - Validation processes OAS content with the `x-openapi-flow` extension
422
+ ## Regeneration Workflow
401
423
 
402
- ## Transition Guidance Fields
424
+ ```bash
425
+ # 1) Generate or update OpenAPI source
426
+ # 2) Initialize sidecar metadata
427
+ npx x-openapi-flow init
428
+ # 3) Edit {context}.x.(json|yaml)
429
+ # 4) Re-apply after each OpenAPI regeneration
430
+ npx x-openapi-flow apply openapi.x.yaml
431
+ ```
403
432
 
404
- - `next_operation_id`: operationId usually called for the next state transition
405
- - `prerequisite_operation_ids`: operationIds expected before a transition
406
- - `prerequisite_field_refs`: required field refs before transition
407
- - `propagated_field_refs`: field refs used by downstream flows
433
+ ---
408
434
 
409
- Field reference format:
435
+ ## Included Examples
410
436
 
411
- - `operationId:request.body.field`
412
- - `operationId:response.<status>.body.field`
437
+ - `payment-api.yaml` (financial)
438
+ - `order-api.yaml` (e-commerce/logistics)
439
+ - `ticket-api.yaml` (support)
440
+ - `quality-warning-api.yaml` (quality warnings)
441
+ - `non-terminating-api.yaml` (non-terminating states)
413
442
 
414
- ## Visualization
443
+ More examples: [docs/wiki/engineering/Real-Examples.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/Real-Examples.md)
415
444
 
416
- ### Swagger UI
445
+ ---
446
+
447
+ ## Repository Structure
448
+
449
+ - [x-openapi-flow/schema/flow-schema.json](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/schema/flow-schema.json): extension JSON Schema contract
450
+ - [x-openapi-flow/lib/validator.js](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/lib/validator.js): schema + graph validation engine
451
+ - [x-openapi-flow/bin/x-openapi-flow.js](https://github.com/tiago-marques/x-openapi-flow/blob/main/x-openapi-flow/bin/x-openapi-flow.js): CLI entrypoint
452
+ - `x-openapi-flow/examples/*.yaml`: sample OpenAPI files
453
+ - [.github/workflows/x-openapi-flow-validate.yml](https://github.com/tiago-marques/x-openapi-flow/blob/main/.github/workflows/x-openapi-flow-validate.yml): CI validation example
454
+
455
+ ---
417
456
 
418
- - UI plugin behavior is covered by tests in `tests/plugins/plugin-ui.test.js`.
419
- - For UI interpretation of `x-openapi-flow`, use `showExtensions: true` with the plugin at `adapters/ui/swagger-ui/x-openapi-flow-plugin.js`.
420
- - A ready HTML example is available at `../example/openapi-swagger-ui/examples/swagger-ui/index.html`.
421
- - The plugin renders a global **Flow Overview** (Mermaid image) near the top of the docs, plus operation-level flow cards.
457
+ ## Changelog
422
458
 
423
- ![Swagger UI integration result](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-extension.png)
459
+ Version history: [CHANGELOG.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/CHANGELOG.md)
460
+ Release notes: [docs/wiki/releases/RELEASE_NOTES_v1.4.0.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/releases/RELEASE_NOTES_v1.4.0.md)
424
461
 
425
- ### Graph Output Example
462
+ ---
426
463
 
427
- `x-openapi-flow graph` includes transition guidance labels in Mermaid output when present (`next_operation_id`, `prerequisite_operation_ids`).
428
- The `graph` command accepts both full OpenAPI source files and sidecar files (`{context}.x.(json|yaml)` and legacy `{context}-openapi-flow.(json|yaml)`).
464
+ ## Documentation Language Policy
429
465
 
430
- ![Guided graph example](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-overview.png)
466
+ All project documentation must be written in English, including:
431
467
 
432
- ## Repository and Documentation
468
+ - Repository Markdown files
469
+ - Wiki pages
470
+ - Release notes and changelog entries
433
471
 
434
- - Repository: https://github.com/tiago-marques/x-openapi-flow
435
- - Full guide and changelog are available in the root repository.
472
+ If a contribution includes non-English documentation content, it should be translated to English before merge.