x-openapi-flow 1.2.3 → 1.3.1

package/README.md

@@ -1,5 +1,7 @@
 # x-openapi-flow
 
+![x-openapi-flow logo](../docs/assets/x-openapi-flow-logo.svg)
+
 CLI and extension contract for documenting and validating resource lifecycle workflows in OpenAPI using `x-openapi-flow`.
 
 ## Overview
@@ -10,7 +12,7 @@ CLI and extension contract for documenting and validating resource lifecycle wor
 - Lifecycle graph consistency
 - Optional quality checks for transitions and references
 
-It also supports a sidecar workflow (`init` + `apply`) to preserve lifecycle metadata when OpenAPI files are regenerated.
+It also supports a sidecar workflow (`init` + `apply`) so lifecycle metadata stays preserved when OpenAPI source files are regenerated.
 
 ## Installation
 
@@ -36,7 +38,7 @@ Use a GitHub PAT with `read:packages` (install) and `write:packages` (publish).
 ## Quick Start
 
 ```bash
-npx x-openapi-flow init openapi.yaml
+npx x-openapi-flow init
 npx x-openapi-flow apply openapi.yaml
 ```
 
@@ -44,34 +46,331 @@ Optional checks:
 
 ```bash
 npx x-openapi-flow validate openapi.yaml --profile strict
+npx x-openapi-flow lint openapi.yaml
 npx x-openapi-flow graph openapi.yaml
 ```
 
 ## CLI Commands
 
 ```bash
-x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
-x-openapi-flow init [openapi-file] [--flows path]
-x-openapi-flow apply [openapi-file] [--flows path] [--out path]
-x-openapi-flow graph <openapi-file> [--format mermaid|json]
-x-openapi-flow doctor [--config path]
+npx x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
+npx x-openapi-flow init [--flows path] [--force] [--dry-run]
+npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]
+npx x-openapi-flow diff [openapi-file] [--flows path] [--format pretty|json]
+npx x-openapi-flow lint [openapi-file] [--format pretty|json] [--config path]
+npx x-openapi-flow analyze [openapi-file] [--format pretty|json] [--out path] [--merge] [--flows path]
+npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
+npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
+npx x-openapi-flow generate-postman [openapi-file] [--output path] [--with-scripts]
+npx x-openapi-flow generate-insomnia [openapi-file] [--output path]
+npx x-openapi-flow generate-redoc [openapi-file] [--output path]
+npx x-openapi-flow graph <openapi-file> [--format mermaid|json]
+npx x-openapi-flow doctor [--config path]
+```
+
+## Output Adapters
+
+`x-openapi-flow` now supports modular output adapters that reuse the same internal flow graph:
+
+- OpenAPI + `x-openapi-flow` -> parser -> graph builder -> adapters
+- Adapters: docs (`export-doc-flows`), SDK (`generate-sdk`), Postman (`generate-postman`), Insomnia (`generate-insomnia`)
+  and Redoc package (`generate-redoc`)
+
+### Redoc/Docs Adapter (`export-doc-flows`)
+
+```bash
+npx x-openapi-flow export-doc-flows openapi.yaml --output ./docs/api-flows.md
+npx x-openapi-flow export-doc-flows openapi.yaml --format json --output ./docs/api-flows.json
+```
+
+Generates a lifecycle page (or JSON model) with:
+
+- Flow/Lifecycle panel per resource
+- Mermaid diagram per resource
+- Current state, prerequisites (`prerequisite_operation_ids`), next operations (`next_operation_id`)
+
+### Redoc Package Adapter (`generate-redoc`)
+
+```bash
+npx x-openapi-flow generate-redoc openapi.yaml --output ./redoc-flow
+```
+
+Generates a ready-to-open Redoc bundle with:
+
+- `index.html` (Redoc + Flow/Lifecycle panel)
+- `x-openapi-flow-redoc-plugin.js` (DOM enhancer)
+- `flow-model.json` (flow graph model)
+- copied OpenAPI spec (`openapi.yaml`/`openapi.json`)
+
+### Postman Adapter (`generate-postman`)
+
+```bash
+npx x-openapi-flow generate-postman openapi.yaml --output ./x-openapi-flow.postman_collection.json --with-scripts
+```
+
+Generates lifecycle-oriented folders/journeys and optional scripts for:
+
+- prerequisite enforcement before request execution
+- propagated operation tracking and ID persistence in collection variables
+
+### Insomnia Adapter (`generate-insomnia`)
+
+```bash
+npx x-openapi-flow generate-insomnia openapi.yaml --output ./x-openapi-flow.insomnia.json
+```
+
+Generates an Insomnia export organized by resource flow groups and ordered requests.
+
+## SDK Generator (`generate-sdk`)
+
+Generate a flow-aware SDK from OpenAPI + `x-openapi-flow` metadata.
+
+```bash
+npx x-openapi-flow generate-sdk openapi.yaml --lang typescript --output ./sdk
 ```
 
+MVP output (TypeScript):
+
+- `src/resources/<Resource>.ts`: resource client + state classes (`PaymentAuthorized`, `PaymentCaptured`, etc.)
+- `src/index.ts`: root `FlowApiClient`
+- `src/http-client.ts`: pluggable HTTP client interface and fetch implementation
+- `src/flow-helpers.ts`: `runFlow("authorize -> capture")`
+- `flow-model.json`: intermediate model `{ resource, operations, prerequisites, nextOperations, states }`
+
+SDK layers (resource-centric):
+
+- Collection/service layer: `api.payments.create()`, `api.payments.retrieve(id)`, `api.payments.list()`
+- Resource instance/state layer: objects expose valid lifecycle transitions (`payment.capture()`, etc.)
+- Optional lifecycle helper methods at service level (`api.payments.capture(id, params, { autoPrerequisites: true })`)
+
+Pipeline used by the generator:
+
+- OpenAPI -> parser -> flow graph -> state machine -> templates -> SDK
+- Reuses lifecycle graph logic from the validator to stay consistent with `validate`, `graph`, and `diff`
+- Transition ordering uses `next_operation_id`, `prerequisite_operation_ids`, and state transitions from `x-openapi-flow`
+
+## Flow Analyzer (`analyze`)
+
+Use `analyze` to bootstrap a sidecar from OpenAPI paths/operation names.
+
+```bash
+npx x-openapi-flow analyze openapi.yaml --out openapi.x.yaml
+npx x-openapi-flow analyze openapi.yaml --format json
+npx x-openapi-flow analyze openapi.yaml --merge --flows openapi.x.yaml
+```
+
+Notes:
+
+- The output is heuristic and intended as a starting point.
+- Inferred states/transitions should be reviewed and adjusted by API/domain owners.
+- Default output format is `pretty`; without `--out`, the suggested sidecar is printed to stdout.
+- `--merge` merges inferred data into an existing sidecar (default path or `--flows`) while preserving existing operation fields.
+- In `json`, inferred transition confidence is available in `analysis.transitionConfidence`.
+
+`diff` now reports field-level changes for operations that already exist in the sidecar.
+In `pretty` format, this appears under `Changed details` with changed paths per operation (for example, `current_state` or `transitions[0].target_state`).
+In `json` format, this appears in `diff.changedOperationDetails`:
+
+```json
+{
+  "diff": {
+    "changedOperationDetails": [
+      {
+        "operationId": "listItems",
+        "changedPaths": ["current_state"]
+      }
+    ]
+  }
+}
+```
+
+### CI usage (`diff` as a gate)
+
+Fail the pipeline when sidecar drift is detected:
+
+```bash
+npx x-openapi-flow diff openapi.yaml --format json | node -e '
+const fs = require("fs");
+const payload = JSON.parse(fs.readFileSync(0, "utf8"));
+const diff = payload.diff || {};
+const changes = (diff.added || 0) + (diff.removed || 0) + (diff.changed || 0);
+if (changes > 0) {
+  console.error("x-openapi-flow diff detected changes. Run init/apply and commit sidecar updates.");
+  process.exit(1);
+}
+'
+```
+
+This keeps `.x` sidecar data aligned with the OpenAPI source in pull requests.
+
+## Semantic lint (`lint`)
+
+Use `lint` to run semantic checks focused on flow modeling quality.
+
+```bash
+npx x-openapi-flow lint openapi.yaml
+npx x-openapi-flow lint openapi.yaml --format json
+```
+
+MVP semantic rules:
+
+- `next_operation_id_exists`
+- `prerequisite_operation_ids_exist`
+- `duplicate_transitions`
+- `terminal_path` (states without path to terminal)
+
+Disable individual rules with config (`x-openapi-flow.config.json`):
+
+```json
+{
+  "lint": {
+    "rules": {
+      "next_operation_id_exists": true,
+      "prerequisite_operation_ids_exist": true,
+      "duplicate_transitions": false,
+      "terminal_path": true
+    }
+  }
+}
+```
+
+## Graph JSON contract (`graph --format json`)
+
+`graph --format json` returns a stable contract for CI/pipeline integrations:
+
+- `format_version`: output contract version (currently `"1.0"`).
+- `flowCount`: number of operations with `x-openapi-flow`.
+- `nodes`: sorted state names (deterministic order).
+- `edges`: sorted transitions by `from`, `to`, `next_operation_id`, and prerequisites.
+- `mermaid`: deterministic Mermaid rendering of the same graph.
+
+Example:
+
+```json
+{
+  "format_version": "1.0",
+  "flowCount": 3,
+  "nodes": ["CONFIRMED", "CREATED", "SHIPPED"],
+  "edges": [
+    {
+      "from": "CONFIRMED",
+      "to": "SHIPPED",
+      "next_operation_id": "shipOrder",
+      "prerequisite_operation_ids": []
+    }
+  ],
+  "mermaid": "stateDiagram-v2\n  state CONFIRMED\n  state CREATED\n  state SHIPPED\n  CONFIRMED --> SHIPPED: next:shipOrder"
+}
+```
+
+## HTTP Methods Support
+
+`init`, `apply`, and `graph` support all OpenAPI 3 HTTP operation methods:
+
+- `get`
+- `put`
+- `post`
+- `delete`
+- `options`
+- `head`
+- `patch`
+- `trace`
+
 ## Sidecar Workflow
 
-`init` always works on an existing OpenAPI file in your repository.
-`init` creates/synchronizes `{context}-openapi-flow.(json|yaml)` as a persistent sidecar for your `x-openapi-flow` data.
-Use `apply` to inject sidecar flows back into regenerated OpenAPI files.
-If no OpenAPI/Swagger file exists yet, generate one first with your framework's official OpenAPI/Swagger tooling.
+Behavior summary:
+
+- `init` works on an existing OpenAPI source file in your repository.
+- `init` creates/synchronizes `{context}.x.(json|yaml)` as a persistent sidecar for `x-openapi-flow` data.
+- If `{context}.flow.(json|yaml)` does not exist, `init` generates it automatically (same merge result as `apply`).
+- If `{context}.flow.(json|yaml)` already exists, `init` asks in interactive mode whether to recreate it.
+- On confirmation (or with `--force`), `init` creates a sidecar backup as `{context}.x.(json|yaml).backup-N` before regenerating `{context}.flow.(json|yaml)`.
+- In non-interactive mode, `init` fails when flow output already exists unless `--force` is provided.
+- With `--dry-run`, `init` prints a summary of sidecar/flow behavior without writing files.
+- Use `apply` to inject sidecar flows back into regenerated OpenAPI source files.
+- If no OpenAPI/Swagger source file exists yet, generate one first with your framework's official tooling.
 
 ### Recommended Sequence
 
 ```bash
-x-openapi-flow init openapi.yaml
-# edit {context}-openapi-flow.(json|yaml)
-x-openapi-flow apply openapi.yaml
+npx x-openapi-flow init
+npx x-openapi-flow init --dry-run
+# edit {context}.x.(json|yaml)
+npx x-openapi-flow diff openapi.yaml
+npx x-openapi-flow apply openapi.yaml
+```
+
+## Sidecar File Contract (all supported fields)
+
+Sidecar top-level shape:
+
+```yaml
+version: "1.0"
+operations:
+  - operationId: createOrder
+    x-openapi-flow:
+      version: "1.0"
+      id: create-order
+      current_state: CREATED
+      description: Creates an order and starts its lifecycle
+      idempotency:
+        header: Idempotency-Key
+        required: true
+      transitions:
+        - target_state: PAID
+          trigger_type: synchronous
+          condition: Payment approved
+          next_operation_id: payOrder
+          prerequisite_operation_ids:
+            - createOrder
+          prerequisite_field_refs:
+            - createOrder:request.body.customer_id
+          propagated_field_refs:
+            - createOrder:response.201.body.order_id
 ```
 
+Top-level (sidecar document):
+
+- `version` (optional, string): sidecar contract version. Default is `"1.0"`.
+- `operations` (optional, array): entries keyed by operation.
+
+Per operation entry:
+
+- `operationId` (recommended, string): target operation identifier in OpenAPI.
+- `x-openapi-flow` (object): lifecycle metadata for that operation.
+- `key` (optional, legacy): backward-compatibility fallback key used by apply.
+
+`x-openapi-flow` fields:
+
+- Required:
+  - `version` (string): currently `"1.0"`.
+  - `id` (string): unique flow id.
+  - `current_state` (string): state represented by this operation.
+- Optional:
+  - `description` (string): human-readable purpose.
+  - `idempotency` (object):
+    - `header` (required, string)
+    - `required` (optional, boolean)
+  - `transitions` (array of transition objects)
+
+Transition object fields:
+
+- Required:
+  - `target_state` (string)
+  - `trigger_type` (enum): `synchronous`, `webhook`, `polling`
+- Optional:
+  - `condition` (string)
+  - `next_operation_id` (string)
+  - `prerequisite_operation_ids` (array of strings)
+  - `prerequisite_field_refs` (array of strings)
+  - `propagated_field_refs` (array of strings)
+
+Field refs format:
+
+- `operationId:request.body.field`
+- `operationId:request.path.paramName`
+- `operationId:response.<status>.body.field`
+
 ## Configuration
 
 Create `x-openapi-flow.config.json` in your project directory:
@@ -105,19 +404,19 @@ Field reference format:
 
 ### Swagger UI
 
-- There is no Swagger UI-based automated test in this repo today (tests are CLI-only).
-- For UI interpretation of `x-openapi-flow`, use `showExtensions: true` plus the plugin at `lib/swagger-ui/x-openapi-flow-plugin.js`.
-- A ready HTML example is available at `examples/swagger-ui/index.html`.
+- UI plugin behavior is covered by tests in `tests/plugins/plugin-ui.test.js`.
+- For UI interpretation of `x-openapi-flow`, use `showExtensions: true` with the plugin at `adapters/ui/swagger-ui/x-openapi-flow-plugin.js`.
+- A ready HTML example is available at `../example-project/examples/swagger-ui/index.html`.
 - The plugin renders a global **Flow Overview** (Mermaid image) near the top of the docs, plus operation-level flow cards.
 
-![Swagger UI integration result](../docs/assets/swagger-ui-integration-result-v2.svg)
+![Swagger UI integration result](../docs/assets/x-openapi-flow-extension.png)
 
 ### Graph Output Example
 
 `x-openapi-flow graph` includes transition guidance labels in Mermaid output when present (`next_operation_id`, `prerequisite_operation_ids`).
-The `graph` command accepts both full OpenAPI files and sidecar files (`{context}-openapi-flow.(json|yaml)`).
+The `graph` command accepts both full OpenAPI source files and sidecar files (`{context}.x.(json|yaml)` and legacy `{context}-openapi-flow.(json|yaml)`).
 
-![Guided graph example](../docs/assets/graph-order-guided.svg)
+![Guided graph example](../docs/assets/x-openapi-flow-overview.png)
 
 ## Repository and Documentation
 

package/adapters/collections/insomnia-adapter.js

@@ -0,0 +1,73 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadApi } = require("../../lib/validator");
+const { buildIntermediateModel } = require("../../lib/sdk-generator");
+const { toTitleCase, pathToPostmanUrl, buildLifecycleSequences } = require("../shared/helpers");
+
+function generateInsomniaWorkspace(options) {
+  const apiPath = path.resolve(options.apiPath);
+  const outputPath = path.resolve(options.outputPath || path.join(process.cwd(), "x-openapi-flow.insomnia.json"));
+
+  const api = loadApi(apiPath);
+  const model = buildIntermediateModel(api);
+
+  const workspaceId = "wrk_x_openapi_flow";
+  const resources = [
+    {
+      _id: workspaceId,
+      _type: "workspace",
+      name: "x-openapi-flow Workspace",
+      description: `Generated from ${apiPath}`,
+      scope: "collection",
+    },
+  ];
+
+  for (const resource of model.resources) {
+    const groupId = `fld_${resource.resourcePropertyName}`;
+    resources.push({
+      _id: groupId,
+      _type: "request_group",
+      parentId: workspaceId,
+      name: `${toTitleCase(resource.resourcePlural || resource.resource)} Flow`,
+    });
+
+    const sequences = buildLifecycleSequences(resource);
+    const operations = sequences.length > 0
+      ? Array.from(new Map(sequences.flat().map((op) => [op.operationId, op])).values())
+      : resource.operations.filter((operation) => operation.hasFlow);
+
+    operations.forEach((operation, index) => {
+      const requestId = `req_${resource.resourcePropertyName}_${index + 1}`;
+      resources.push({
+        _id: requestId,
+        _type: "request",
+        parentId: groupId,
+        name: operation.operationId,
+        method: String(operation.httpMethod || "get").toUpperCase(),
+        url: `{{ base_url }}${pathToPostmanUrl(operation.path, resource.resourcePropertyName)}`,
+        body: {},
+      });
+    });
+  }
+
+  const exportPayload = {
+    _type: "export",
+    __export_format: 4,
+    __export_date: new Date().toISOString(),
+    __export_source: "x-openapi-flow",
+    resources,
+  };
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(exportPayload, null, 2)}\n`, "utf8");
+
+  return {
+    outputPath,
+    resources: model.resources.length,
+    flowCount: model.flowCount,
+  };
+}
+
+module.exports = { generateInsomniaWorkspace };

package/adapters/collections/postman-adapter.js

@@ -0,0 +1,145 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadApi } = require("../../lib/validator");
+const { buildIntermediateModel } = require("../../lib/sdk-generator");
+const { toTitleCase, pathToPostmanUrl, buildLifecycleSequences } = require("../shared/helpers");
+
+function buildPostmanItem(operation, resource) {
+  const rawPath = pathToPostmanUrl(operation.path, resource.resourcePropertyName);
+  const urlRaw = `{{baseUrl}}${rawPath}`;
+
+  const item = {
+    name: operation.operationId,
+    request: {
+      method: String(operation.httpMethod || "get").toUpperCase(),
+      header: [
+        {
+          key: "Content-Type",
+          value: "application/json",
+          type: "text",
+        },
+      ],
+      url: {
+        raw: urlRaw,
+        host: ["{{baseUrl}}"],
+        path: rawPath.split("/").filter(Boolean),
+      },
+    },
+    response: [],
+  };
+
+  if (["POST", "PUT", "PATCH"].includes(item.request.method)) {
+    item.request.body = {
+      mode: "raw",
+      raw: "{}",
+      options: { raw: { language: "json" } },
+    };
+  }
+
+  return item;
+}
+
+function addPostmanScripts(item, operation, resource) {
+  const prereqs = JSON.stringify(operation.prerequisites || []);
+  const operationId = operation.operationId;
+  const idCandidateKey = `${resource.resourcePropertyName}Id`;
+
+  item.event = [
+    {
+      listen: "prerequest",
+      script: {
+        type: "text/javascript",
+        exec: [
+          `const required = ${prereqs};`,
+          "const executed = JSON.parse(pm.collectionVariables.get('flowExecutedOps') || '[]');",
+          "const missing = required.filter((operationId) => !executed.includes(operationId));",
+          "if (missing.length > 0) {",
+          `  throw new Error('Missing prerequisites for ${operationId}: ' + missing.join(', '));`,
+          "}",
+        ],
+      },
+    },
+    {
+      listen: "test",
+      script: {
+        type: "text/javascript",
+        exec: [
+          "const payload = pm.response.json ? pm.response.json() : {};",
+          `if (payload && payload.id) pm.collectionVariables.set('${idCandidateKey}', payload.id);`,
+          "const executed = JSON.parse(pm.collectionVariables.get('flowExecutedOps') || '[]');",
+          `if (!executed.includes('${operationId}')) executed.push('${operationId}');`,
+          "pm.collectionVariables.set('flowExecutedOps', JSON.stringify(executed));",
+        ],
+      },
+    },
+  ];
+}
+
+function generatePostmanCollection(options) {
+  const apiPath = path.resolve(options.apiPath);
+  const outputPath = path.resolve(options.outputPath || path.join(process.cwd(), "x-openapi-flow.postman_collection.json"));
+  const withScripts = options.withScripts !== false;
+
+  const api = loadApi(apiPath);
+  const model = buildIntermediateModel(api);
+
+  const collection = {
+    info: {
+      name: "x-openapi-flow Lifecycle Collection",
+      schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+      description: `Generated from ${apiPath}`,
+    },
+    item: [],
+    variable: [
+      { key: "baseUrl", value: "http://localhost:3000" },
+      { key: "flowExecutedOps", value: "[]" },
+    ],
+  };
+
+  for (const resource of model.resources) {
+    const sequences = buildLifecycleSequences(resource);
+    const folder = {
+      name: `${toTitleCase(resource.resourcePlural || resource.resource)} Lifecycle`,
+      item: [],
+    };
+
+    if (sequences.length === 0) {
+      const fallbackItems = resource.operations
+        .filter((operation) => operation.hasFlow)
+        .map((operation) => {
+          const item = buildPostmanItem(operation, resource);
+          if (withScripts) addPostmanScripts(item, operation, resource);
+          return item;
+        });
+      folder.item.push(...fallbackItems);
+    } else {
+      sequences.forEach((sequence, index) => {
+        const journey = {
+          name: `Journey ${index + 1}`,
+          item: sequence.map((operation) => {
+            const item = buildPostmanItem(operation, resource);
+            if (withScripts) addPostmanScripts(item, operation, resource);
+            return item;
+          }),
+        };
+        folder.item.push(journey);
+      });
+    }
+
+    collection.item.push(folder);
+  }
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(collection, null, 2)}\n`, "utf8");
+
+  return {
+    outputPath,
+    resources: model.resources.length,
+    flowCount: model.flowCount,
+    withScripts,
+  };
+}
+
+module.exports = { generatePostmanCollection };