x-openapi-flow 1.4.4 → 1.5.1

package/README.md

@@ -1,5 +1,9 @@
 <!-- Auto-generated from /README.md via scripts/sync-package-readme.js. Do not edit directly. -->
 
+# OpenAPI describes APIs. x-openapi-flow turns them into executable workflows — for developers and AI agents.
+
+## Define your API workflows in openapi.x.json and execute them without writing custom clients or orchestration logic.
+
 ![x-openapi-flow logo](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/x-openapi-flow-logo.svg)
 
 [![npm version](https://img.shields.io/npm/v/x-openapi-flow?label=npm%20version)](https://www.npmjs.com/package/x-openapi-flow)
@@ -11,21 +15,69 @@
 [![open issues](https://img.shields.io/github/issues/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/issues)
 [![last commit](https://img.shields.io/github/last-commit/tiago-marques/x-openapi-flow)](https://github.com/tiago-marques/x-openapi-flow/commits/main)
 ![copilot ready](https://img.shields.io/badge/Copilot-Ready-00BFA5?logo=githubcopilot&logoColor=white)
-> 🚀 1,400+ downloads in the first 3 weeks!
-
-# OpenAPI describes APIs. x-openapi-flow describes their workflows — for developers and AI.
+> 🚀 2,100+ downloads in the first 3 weeks!
 
-![x-openapi-flow in action](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/ezgif.com-animated-gif-maker.gif)
+## ⚡ Get started in seconds
+> npx x-openapi-flow init
 
+### This generates an openapi.x.json file where you can declaratively define how your API should be executed — not just described.
 
 > See your API lifecycle come alive from your OpenAPI spec, with one simple command
 
 > Validate, document, and generate flow-aware SDKs automatically.
 
+![x-openapi-flow in action](https://raw.githubusercontent.com/tiago-marques/x-openapi-flow/main/docs/assets/ezgif.com-animated-gif-maker.gif)
+
+## What is this?
+
+### x-openapi-flow extends your OpenAPI specification with a workflow layer.
+
+> openapi.json → describes your API  
+> openapi.x.json → describes how to use it (flows)
+
+### Instead of writing imperative code to orchestrate API calls, you define workflows declaratively and run them anywhere.
+
 `x-openapi-flow` adds a **declarative state machine** to your OpenAPI spec.
 
 Model resource lifecycles, enforce valid transitions, and generate flow-aware artifacts for documentation, SDKs, and automation.
 
+## 🚀 Example
+
+> Define stateful workflows and lifecycle transitions directly inside your OpenAPI operations:
+
+```json
+{
+  "operationId": "createOrder",
+  "x-openapi-flow": {
+    "id": "create-order",
+    "current_state": "created",
+    "description": "Creates an order and starts the lifecycle",
+    "transitions": [
+      {
+        "trigger_type": "synchronous",
+        "condition": "Payment is confirmed",
+        "target_state": "paid",
+        "next_operation_id": "payOrder",
+        "prerequisite_operation_ids": ["createOrder"],
+        "propagated_field_refs": [
+          "createOrder:response.201.body.order_id"
+        ]
+      }
+    ]
+  }
+}
+```
+
+This flow defines an order lifecycle directly inside your OpenAPI:
+
+* Starts in the `created` state
+* Transitions to `paid` when payment is confirmed
+* Supports both synchronous and polling-based transitions
+* Propagates data between operations automatically
+
+Instead of manually orchestrating API calls, the workflow is fully described alongside your API specification.
+
+
 ## Why This Exists
 
 Building APIs is cheap. Building **complex, multi-step APIs that teams actually use correctly** is hard.  
@@ -52,7 +104,37 @@ Turn your OpenAPI spec into a single source of truth for API behavior:
 - Export [Postman](#postman-demo) and [Insomnia](#insomnia-demo) collections organized by lifecycle
 - Create [AI-ready API contracts](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/engineering/AI-Sidecar-Authoring.md) for agentic integrations
 
-## Quick Start
+## Quick Start (without OpenAPI file)
+
+Fastest way to see value (guided scaffold):
+
+```bash
+npx x-openapi-flow quickstart
+cd x-openapi-flow-quickstart
+npm install
+npm start
+```
+
+Optional runtime:
+
+```bash
+npx x-openapi-flow quickstart --runtime fastify
+```
+
+Then run:
+
+```bash
+curl -s -X POST http://localhost:3110/orders
+curl -i -X POST http://localhost:3110/orders/<id>/ship
+```
+
+Expected: `409 INVALID_STATE_TRANSITION`.
+
+---
+### If you already have an OpenAPI file, use the sidecar workflow:
+
+
+
 
 Initialize flow support in your project:
 
@@ -76,6 +158,12 @@ This will:
 
 💡 Tip: run this in CI to enforce API workflow correctness
 
+### Less Verbose DSL for Large Flows
+
+For larger APIs, you can define flow rules by resource (with shared transitions/defaults) and reduce duplication in sidecar files.
+
+See: [Sidecar Contract](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Sidecar-Contract.md)
+
 <a id="mermaid-example"></a>
 ### Real Lifecycle Example
 
@@ -124,6 +212,147 @@ await payment.capture();
 
 > This SDK guides developers through valid transition paths, following patterns used by market leaders to ensure safe and intuitive integrations.
 
+## Runtime Enforcement (Express + Fastify)
+
+CI validation is important, but production safety needs request-time enforcement.
+
+`x-openapi-flow` now includes an official runtime guard for Node.js that can block invalid state transitions during request handling.
+
+- Works with **Express** and **Fastify**
+- Resolves operations by `operationId` (when available) or by method + route
+- Reads current resource state using your own persistence callback
+- Blocks invalid transitions with explicit `409` error payloads
+
+Install and use directly in your API server:
+
+```js
+const {
+  createExpressFlowGuard,
+  createFastifyFlowGuard,
+} = require("x-openapi-flow/lib/runtime-guard");
+```
+
+Express example:
+
+```js
+const express = require("express");
+const { createExpressFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
+const openapi = require("./openapi.flow.json");
+
+const app = express();
+
+app.use(
+  createExpressFlowGuard({
+    openapi,
+    async getCurrentState({ resourceId }) {
+      if (!resourceId) return null;
+      return paymentStore.getState(resourceId); // your DB/service lookup
+    },
+    resolveResourceId: ({ params }) => params.id || null,
+  })
+);
+```
+
+Fastify example:
+
+```js
+const fastify = require("fastify")();
+const { createFastifyFlowGuard } = require("x-openapi-flow/lib/runtime-guard");
+const openapi = require("./openapi.flow.json");
+
+fastify.addHook(
+  "preHandler",
+  createFastifyFlowGuard({
+    openapi,
+    async getCurrentState({ resourceId }) {
+      if (!resourceId) return null;
+      return paymentStore.getState(resourceId);
+    },
+    resolveResourceId: ({ params }) => params.id || null,
+  })
+);
+```
+
+Error payload for blocked transition:
+
+```json
+{
+  "error": {
+    "code": "INVALID_STATE_TRANSITION",
+    "message": "Blocked invalid transition for operation 'capturePayment'. Current state 'CREATED' cannot transition to this operation.",
+    "operation_id": "capturePayment",
+    "current_state": "CREATED",
+    "allowed_from_states": ["AUTHORIZED"],
+    "resource_id": "pay_123"
+  }
+}
+```
+
+More details: [Runtime Guard](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/Runtime-Guard.md)
+
+### 5-Minute Demo: Real Runtime Block (E-commerce Orders)
+
+Want to see the value immediately? Use the official minimal demo:
+
+- [example/runtime-guard/minimal-order/README.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/example/runtime-guard/minimal-order/README.md)
+
+Run in under 5 minutes:
+
+```bash
+cd example/runtime-guard/minimal-order
+npm install
+npm start
+```
+
+Create an order, then try to ship before payment (must return `409 INVALID_STATE_TRANSITION`):
+
+```bash
+curl -s -X POST http://localhost:3110/orders
+curl -i -X POST http://localhost:3110/orders/<id>/ship
+```
+
+HTTPie equivalent:
+
+```bash
+http POST :3110/orders
+http -v POST :3110/orders/<id>/ship
+```
+
+## Programmatic State Machine Engine
+
+Use a reusable deterministic engine independently of CLI and OpenAPI parsing:
+
+```js
+const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");
+
+const engine = createStateMachineEngine({
+  transitions: [
+    { from: "CREATED", action: "confirm", to: "CONFIRMED" },
+    { from: "CONFIRMED", action: "ship", to: "SHIPPED" },
+  ],
+});
+
+engine.canTransition("CREATED", "confirm");
+engine.getNextState("CREATED", "confirm");
+engine.validateFlow({ startState: "CREATED", actions: ["confirm", "ship"] });
+```
+
+More details: [State Machine Engine](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/State-Machine-Engine.md)
+
+### OpenAPI to Engine Adapter
+
+Convert `x-openapi-flow` metadata to a pure engine definition:
+
+```js
+const { createStateMachineAdapterModel } = require("x-openapi-flow/lib/openapi-state-machine-adapter");
+const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");
+
+const model = createStateMachineAdapterModel({ openapiPath: "./openapi.flow.yaml" });
+const engine = createStateMachineEngine(model.definition);
+```
+
+More details: [OpenAPI State Machine Adapter](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/OpenAPI-State-Machine-Adapter.md)
+
 ## Who Benefits Most
 
 x-openapi-flow is ideal for teams and organizations that want **clear, enforceable API workflows**:
@@ -227,6 +456,8 @@ npx x-openapi-flow version                # show version
 npx x-openapi-flow doctor [--config path] # check setup and config
 
 npx x-openapi-flow completion [bash|zsh]  # enable shell autocompletion
+
+npx x-openapi-flow quickstart [--dir path] [--runtime express|fastify] [--force] # scaffold runnable onboarding project
 ```
 
 ### Workflow Management
@@ -239,7 +470,7 @@ npx x-openapi-flow init [--flows path] [--force] [--dry-run]
 npx x-openapi-flow apply [openapi-file] [--flows path] [--out path]  
 
 # validate transitions
-npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality]  
+npx x-openapi-flow validate <openapi-file> [--profile core|relaxed|strict] [--strict-quality] [--semantic]  
 ```
 
 ### Visualization & Documentation
@@ -262,6 +493,16 @@ npx x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format mar
 npx x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path] 
 ```
 
+### Test Generation
+
+```bash
+# generate executable flow tests (happy path + invalid transitions)
+npx x-openapi-flow generate-flow-tests [openapi-file] [--format jest|vitest|postman] [--output path]
+
+# postman/newman-oriented collection with flow scripts
+npx x-openapi-flow generate-flow-tests [openapi-file] --format postman [--output path] [--with-scripts]
+```
+
 Full details:  
 
 - [CLI-Reference.md](https://github.com/tiago-marques/x-openapi-flow/blob/main/docs/wiki/reference/CLI-Reference.md)  

package/adapters/flow-output-adapters.js

@@ -6,10 +6,12 @@ const { exportDocFlows } = require("./docs/doc-adapter");
 const { generatePostmanCollection } = require("./collections/postman-adapter");
 const { generateInsomniaWorkspace } = require("./collections/insomnia-adapter");
 const { generateRedocPackage } = require("./ui/redoc-adapter");
+const { generateFlowTests } = require("./tests/flow-test-adapter");
 
 module.exports = {
   exportDocFlows,
   generatePostmanCollection,
   generateInsomniaWorkspace,
   generateRedocPackage,
+  generateFlowTests,
 };

package/adapters/tests/flow-test-adapter.js

@@ -0,0 +1,254 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { loadApi } = require("../../lib/validator");
+const { createStateMachineAdapterModel } = require("../../lib/openapi-state-machine-adapter");
+const { createStateMachineEngine } = require("../../lib/state-machine-engine");
+const { generatePostmanCollection } = require("../collections/postman-adapter");
+
+function getFormat(options) {
+  const format = String(options.format || "jest").toLowerCase();
+  if (!["jest", "vitest", "postman"].includes(format)) {
+    throw new Error(`Unsupported test format '${format}'. Use 'jest', 'vitest', or 'postman'.`);
+  }
+  return format;
+}
+
+function getDefaultOutputPath(format) {
+  if (format === "postman") {
+    return path.resolve(process.cwd(), "x-openapi-flow.flow-tests.postman_collection.json");
+  }
+
+  if (format === "vitest") {
+    return path.resolve(process.cwd(), "x-openapi-flow.flow.generated.vitest.test.js");
+  }
+
+  return path.resolve(process.cwd(), "x-openapi-flow.flow.generated.jest.test.js");
+}
+
+function buildHappyPaths(engine) {
+  const transitions = engine.getTransitions();
+  const outgoing = new Map();
+  const indegree = new Map();
+  const states = engine.getStates();
+
+  for (const state of states) {
+    outgoing.set(state, []);
+    indegree.set(state, 0);
+  }
+
+  for (const transition of transitions) {
+    if (!outgoing.has(transition.from)) {
+      outgoing.set(transition.from, []);
+    }
+    outgoing.get(transition.from).push(transition);
+    indegree.set(transition.to, (indegree.get(transition.to) || 0) + 1);
+  }
+
+  for (const transitionList of outgoing.values()) {
+    transitionList.sort((left, right) => left.action.localeCompare(right.action));
+  }
+
+  const starts = states.filter((state) => (indegree.get(state) || 0) === 0);
+  const roots = starts.length > 0 ? starts : states;
+  const maxDepth = Math.max(3, states.length + 2);
+  const maxPaths = 50;
+  const paths = [];
+
+  function walk(currentState, actions, visitedKeys, depth) {
+    if (paths.length >= maxPaths) {
+      return;
+    }
+
+    const nextTransitions = outgoing.get(currentState) || [];
+    if (nextTransitions.length === 0 || depth >= maxDepth) {
+      if (actions.length > 0) {
+        paths.push({
+          startState: actions[0].from,
+          actions: actions.map((entry) => entry.action),
+          finalState: currentState,
+        });
+      }
+      return;
+    }
+
+    for (const transition of nextTransitions) {
+      const visitKey = `${transition.from}::${transition.action}::${transition.to}`;
+      if (visitedKeys.has(visitKey)) {
+        continue;
+      }
+
+      const nextVisited = new Set(visitedKeys);
+      nextVisited.add(visitKey);
+
+      walk(
+        transition.to,
+        actions.concat([{ from: transition.from, action: transition.action }]),
+        nextVisited,
+        depth + 1
+      );
+    }
+  }
+
+  for (const root of roots) {
+    walk(root, [], new Set(), 0);
+  }
+
+  const dedup = new Map();
+  for (const entry of paths) {
+    const key = `${entry.startState}::${entry.actions.join(",")}`;
+    if (!dedup.has(key)) {
+      dedup.set(key, entry);
+    }
+  }
+
+  return [...dedup.values()];
+}
+
+function buildInvalidCases(engine) {
+  const transitions = engine.getTransitions();
+  const states = engine.getStates();
+  const knownActions = [...new Set(transitions.map((transition) => transition.action))].sort();
+  const cases = [];
+
+  for (const state of states) {
+    const available = engine.getAvailableActions(state);
+    const disallowedAction = knownActions.find((action) => !available.includes(action));
+
+    if (disallowedAction) {
+      cases.push({
+        state,
+        action: disallowedAction,
+        availableActions: available,
+      });
+      continue;
+    }
+
+    cases.push({
+      state,
+      action: "__invalid_action__",
+      availableActions: available,
+    });
+  }
+
+  return cases;
+}
+
+function buildJestOrVitestContent({ format, sourcePath, definition, happyPaths, invalidCases }) {
+  const frameworkPrelude = format === "vitest"
+    ? "const { describe, test, expect } = require(\"vitest\");\n"
+    : "";
+
+  const title = format === "vitest" ? "Vitest" : "Jest";
+
+  return `"use strict";
+
+${frameworkPrelude}const { createStateMachineEngine } = require("x-openapi-flow/lib/state-machine-engine");
+
+const definition = ${JSON.stringify(definition, null, 2)};
+const happyPaths = ${JSON.stringify(happyPaths, null, 2)};
+const invalidCases = ${JSON.stringify(invalidCases, null, 2)};
+
+describe("x-openapi-flow generated tests (${title})", () => {
+  const engine = createStateMachineEngine(definition);
+
+  test("has transitions in definition", () => {
+    expect(Array.isArray(definition.transitions)).toBe(true);
+    expect(definition.transitions.length).toBeGreaterThan(0);
+  });
+
+  describe("happy paths", () => {
+    for (const pathCase of happyPaths) {
+      test(
+        \`valid flow: \${pathCase.startState} -> \${pathCase.actions.join(" -> ")}\`,
+        () => {
+          const result = engine.validateFlow({
+            startState: pathCase.startState,
+            actions: pathCase.actions,
+          });
+
+          expect(result.ok).toBe(true);
+          expect(result.finalState).toBe(pathCase.finalState);
+        }
+      );
+    }
+  });
+
+  describe("invalid transitions", () => {
+    for (const invalidCase of invalidCases) {
+      test(
+        \`blocks invalid action \${invalidCase.action} from state \${invalidCase.state}\`,
+        () => {
+          expect(engine.canTransition(invalidCase.state, invalidCase.action)).toBe(false);
+
+          const result = engine.validateFlow({
+            startState: invalidCase.state,
+            actions: [invalidCase.action],
+          });
+
+          expect(result.ok).toBe(false);
+          expect(result.error.code).toBe("INVALID_TRANSITION");
+          expect(Array.isArray(result.error.availableActions)).toBe(true);
+        }
+      );
+    }
+  });
+});
+
+// Generated from: ${sourcePath}
+`;
+}
+
+function generateFlowTests(options) {
+  const format = getFormat(options || {});
+  const apiPath = path.resolve(options.apiPath);
+  const outputPath = path.resolve(options.outputPath || getDefaultOutputPath(format));
+
+  if (format === "postman") {
+    const postman = generatePostmanCollection({
+      apiPath,
+      outputPath,
+      withScripts: options.withScripts !== false,
+    });
+
+    return {
+      format,
+      outputPath: postman.outputPath,
+      flowCount: postman.flowCount,
+      happyPathTests: null,
+      invalidCaseTests: null,
+      withScripts: postman.withScripts,
+    };
+  }
+
+  const api = loadApi(apiPath);
+  const model = createStateMachineAdapterModel({ openapi: api });
+  const engine = createStateMachineEngine(model.definition);
+
+  const happyPaths = buildHappyPaths(engine);
+  const invalidCases = buildInvalidCases(engine);
+  const content = buildJestOrVitestContent({
+    format,
+    sourcePath: apiPath,
+    definition: model.definition,
+    happyPaths,
+    invalidCases,
+  });
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, content, "utf8");
+
+  return {
+    format,
+    outputPath,
+    flowCount: model.definition.transitions.length,
+    happyPathTests: happyPaths.length,
+    invalidCaseTests: invalidCases.length,
+    withScripts: null,
+  };
+}
+
+module.exports = {
+  generateFlowTests,
+};