From 2e1be36c81df9f58254ba450a3b21cae95d78699 Mon Sep 17 00:00:00 2001 From: Vishnu R Date: Tue, 22 Sep 2026 21:19:42 +0530 Subject: [PATCH 1/3] release: prepare the Node disagreement loop as 3.5.0 Client and backend 3.5.0 and CLI 0.8.0 sit in the in-flight window so the check, the finding, and the API Client handoff can be installed. Examples stay on the published artifacts until those three exist. Signed-off-by: Vishnu R --- CHANGELOG.md | 9 ++++++++- docs/host-execution-operations.md | 2 +- docs/releases/3.5.0.md | 29 +++++++++++++++++++++++++++++ package-lock.json | 4 ++-- packages/backend/package.json | 2 +- packages/client/package.json | 2 +- scripts/release-versions.json | 8 ++++++-- tools/flexdoc-cli/package.json | 2 +- 8 files changed, 49 insertions(+), 9 deletions(-) create mode 100644 docs/releases/3.5.0.md diff --git a/CHANGELOG.md b/CHANGELOG.md index efc73c28..678c2ad3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,16 @@ Notable FlexDoc product releases are recorded here. Detailed release notes remai ## Unreleased -- An implemented route that OpenAPI does not document fails `flexdoc validate` when runtime discovery is complete, and the failure names the method and path. Partial discovery keeps that finding a warning. `runtimeIntelligence.acknowledgedUndocumented` records that route as acknowledged info. The route stays registered, `summary.runtime` still counts it, and the acknowledgement does not fail validation. +## 3.5.0 — Node disagreement loop + +`@prauga/flexdoc-client` and `@prauga/flexdoc-backend` **3.5.0**, with `@prauga/flexdoc-cli` **0.8.0**. Native adapter versions are unchanged. + +- An implemented route that OpenAPI does not document fails `flexdoc validate` when runtime discovery is complete, and the failure names the method and path. Partial discovery keeps that finding a warning. A service that previously passed validation with only that warning now fails the default check. +- `runtimeIntelligence.acknowledgedUndocumented` records a chosen route as acknowledged info. The route stays registered, `summary.runtime` still counts it, and the acknowledgement does not fail validation. - Opening that finding shows the missing contract beside the registered method and path, and can send it from the API Client. The URL uses the snapshot `serverOrigin` when present, and is same-origin otherwise. The request asks to prefer the API host only when host execution is available and the server has not opted out. +See [`docs/releases/3.5.0.md`](docs/releases/3.5.0.md). + ## 3.4.0 — 3.3.x hardening package release Package semver is independent from internal product-milestone labels: **3.4.0** publishes the completed 3.3.x hardening stack. diff --git a/docs/host-execution-operations.md b/docs/host-execution-operations.md index 3663f906..a9bafcd3 100644 --- a/docs/host-execution-operations.md +++ b/docs/host-execution-operations.md @@ -1,6 +1,6 @@ # API-host execution operations and abuse controls -This guidance is part of the `@prauga/flexdoc-backend` **3.4.0** host-execution contract. FlexDoc API-host execution is an application-owned server capability. When it is available, an interactive browser request can become two network hops: browser -> API host -> target API. The execute endpoint therefore consumes API-host CPU, memory, sockets, outbound bandwidth, DNS/TLS work, and target-service capacity in addition to the ordinary documentation request. +This guidance is the `@prauga/flexdoc-backend` **3.5.0** host-execution contract, unchanged from 3.4.0. FlexDoc API-host execution is an application-owned server capability. When it is available, an interactive browser request can become two network hops: browser -> API host -> target API. The execute endpoint therefore consumes API-host CPU, memory, sockets, outbound bandwidth, DNS/TLS work, and target-service capacity in addition to the ordinary documentation request. The built-in executor safety policy is necessary but is not an application abuse policy. Exact-origin allowlists, DNS/address pinning, redirect validation, request/response size bounds, execution deadlines, and `X-FlexDoc-Execute: 1` prevent classes of unsafe execution; they do not identify the caller or decide how much work one authenticated user may cause. diff --git a/docs/releases/3.5.0.md b/docs/releases/3.5.0.md new file mode 100644 index 00000000..9642dcfa --- /dev/null +++ b/docs/releases/3.5.0.md @@ -0,0 +1,29 @@ +# FlexDoc package release 3.5.0 + +FlexDoc **3.5.0** publishes the Node disagreement loop. Package semver stays independent of product-milestone labels. + +## Package versions + +- `@prauga/flexdoc-client` — **3.5.0** +- `@prauga/flexdoc-backend` — **3.5.0** +- `@prauga/flexdoc-cli` — **0.8.0** + +`@prauga/flexdoc-core` and the native adapter lines are unchanged. This wave does not change their behavior. Examples and the install tables stay on the artifacts a user can install today, and move to these versions in the post-publish repin. + +## What changes for an existing Node service + +When runtime discovery is complete, an implemented route that OpenAPI does not document is an error. `flexdoc validate` exits 1 and names the method and path. Partial discovery keeps that finding a warning. A check that previously passed because the only disagreement was that warning now fails. + +`runtimeIntelligence.acknowledgedUndocumented` marks a chosen route as acknowledged info. The route remains in the runtime record, `summary.runtime` still counts it, and the acknowledgement does not fail validation. + +Opening the finding shows the missing contract beside the registered method and path. The API Client can send that route. The URL uses the snapshot `serverOrigin` when the runtime reported one, and is a same-origin path otherwise. The request prefers the API host only when host execution is available and the server has not set `preferHostExecution` to false. + +The page does not invent a handler, a schema, parameters, or auth for a route the contract does not declare. + +## Host execution + +The `@prauga/flexdoc-backend` **3.5.0** host-execution contract is unchanged from 3.4.0. [`docs/host-execution-operations.md`](../host-execution-operations.md) still describes that contract. + +## Release sequencing + +This wave uses the version contract's in-flight window. Source versions for the client, backend, and CLI sit ahead of the registry. After those three artifacts exist, the follow-up repin updates examples, generated lock metadata, and the published baselines, then clears `pending`. diff --git a/package-lock.json b/package-lock.json index f7e65db7..7e0a3541 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12052,7 +12052,7 @@ }, "packages/backend": { "name": "@prauga/flexdoc-backend", - "version": "3.4.0", + "version": "3.5.0", "license": "Apache-2.0", "dependencies": { "jsonwebtoken": "^9.0.2", @@ -12090,7 +12090,7 @@ }, "packages/client": { "name": "@prauga/flexdoc-client", - "version": "3.4.0", + "version": "3.5.0", "license": "Apache-2.0", "dependencies": { "@codemirror/commands": "^6.11.0", diff --git a/packages/backend/package.json b/packages/backend/package.json index 7bc8e577..7ed2dd3c 100644 --- a/packages/backend/package.json +++ b/packages/backend/package.json @@ -1,6 +1,6 @@ { "name": "@prauga/flexdoc-backend", - "version": "3.4.0", + "version": "3.5.0", "description": "Thin self-hosted FlexDoc integrations for Express, Fastify, and NestJS", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/packages/client/package.json b/packages/client/package.json index 97369a2f..ea8b6a3a 100644 --- a/packages/client/package.json +++ b/packages/client/package.json @@ -1,6 +1,6 @@ { "name": "@prauga/flexdoc-client", - "version": "3.4.0", + "version": "3.5.0", "description": "FlexDoc's canonical self-hosted OpenAPI renderer, API explorer, and React components", "type": "module", "main": "./dist/flexdoc.umd.cjs", diff --git a/scripts/release-versions.json b/scripts/release-versions.json index 205ad32a..060574b5 100644 --- a/scripts/release-versions.json +++ b/scripts/release-versions.json @@ -15,6 +15,10 @@ "go": "0.6.0", "elixir": "0.5.0" }, - "pending": {}, - "sourceReleaseDocument": "docs/releases/3.4.0.md" + "pending": { + "client": "3.5.0", + "backend": "3.5.0", + "cli": "0.8.0" + }, + "sourceReleaseDocument": "docs/releases/3.5.0.md" } diff --git a/tools/flexdoc-cli/package.json b/tools/flexdoc-cli/package.json index 5df7bf7c..19b09654 100644 --- a/tools/flexdoc-cli/package.json +++ b/tools/flexdoc-cli/package.json @@ -1,6 +1,6 @@ { "name": "@prauga/flexdoc-cli", - "version": "0.7.0", + "version": "0.8.0", "description": "Build, serve, validate, and run self-hosted FlexDoc/OpenAPI workflows from the CLI", "type": "module", "bin": { "flexdoc": "./bin/flexdoc.js" }, From 0a85aa990a451c005b833413610059ce1de61095 Mon Sep 17 00:00:00 2001 From: Vishnu R Date: Tue, 22 Sep 2026 21:53:36 +0530 Subject: [PATCH 2/3] fix: record published 3.4.0 example installs in the lockfile The workspace packages are 3.5.0, so the examples that stay on the published artifacts need their own registry entries or npm ci rejects the lockfile. Signed-off-by: Vishnu R --- package-lock.json | 98 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/package-lock.json b/package-lock.json index 7e0a3541..4880b7a7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -71,6 +71,24 @@ "vite": "^7.3.6" } }, + "examples/api-client/node_modules/@prauga/flexdoc-client": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@prauga/flexdoc-client/-/flexdoc-client-3.4.0.tgz", + "integrity": "sha512-3vK1WWLdL1WqGhbap1NEzsHIvIPAgze8z5T+qG6aZTHjX5qZxE9OqctNGVQl0xtQa9ldY3TcfKd5OZ8mCIVJNA==", + "license": "AGPL-3.0-or-later", + "dependencies": { + "@codemirror/commands": "^6.11.0", + "@codemirror/state": "^6.7.4", + "@codemirror/view": "^6.43.11", + "js-yaml": "^4.1.0", + "lucide-react": "^0.525.0", + "prismjs": "^1.29.0" + }, + "peerDependencies": { + "react": "^19.0.0", + "react-dom": "^19.0.0" + } + }, "examples/basic-usage": { "name": "flexdoc-basic-example", "version": "0.1.0", @@ -92,6 +110,33 @@ "vite": "^7.3.6" } }, + "examples/basic-usage/node_modules/@prauga/flexdoc-client": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@prauga/flexdoc-client/-/flexdoc-client-3.4.0.tgz", + "integrity": "sha512-3vK1WWLdL1WqGhbap1NEzsHIvIPAgze8z5T+qG6aZTHjX5qZxE9OqctNGVQl0xtQa9ldY3TcfKd5OZ8mCIVJNA==", + "license": "AGPL-3.0-or-later", + "dependencies": { + "@codemirror/commands": "^6.11.0", + "@codemirror/state": "^6.7.4", + "@codemirror/view": "^6.43.11", + "js-yaml": "^4.1.0", + "lucide-react": "^0.525.0", + "prismjs": "^1.29.0" + }, + "peerDependencies": { + "react": "^19.0.0", + "react-dom": "^19.0.0" + } + }, + "examples/basic-usage/node_modules/@prauga/flexdoc-client/node_modules/lucide-react": { + "version": "0.525.0", + "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.525.0.tgz", + "integrity": "sha512-Tm1txJ2OkymCGkvwoHt33Y2JpN5xucVq1slHcgE6Lk0WjDfjgKWor5CdVER8U6DvcfMwh4M8XxmpTiyzfmfDYQ==", + "license": "ISC", + "peerDependencies": { + "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, "examples/basic-usage/node_modules/lucide-react": { "version": "1.38.0", "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.38.0.tgz", @@ -122,6 +167,33 @@ "vite": "^7.3.6" } }, + "examples/interactive-demo/node_modules/@prauga/flexdoc-client": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@prauga/flexdoc-client/-/flexdoc-client-3.4.0.tgz", + "integrity": "sha512-3vK1WWLdL1WqGhbap1NEzsHIvIPAgze8z5T+qG6aZTHjX5qZxE9OqctNGVQl0xtQa9ldY3TcfKd5OZ8mCIVJNA==", + "license": "AGPL-3.0-or-later", + "dependencies": { + "@codemirror/commands": "^6.11.0", + "@codemirror/state": "^6.7.4", + "@codemirror/view": "^6.43.11", + "js-yaml": "^4.1.0", + "lucide-react": "^0.525.0", + "prismjs": "^1.29.0" + }, + "peerDependencies": { + "react": "^19.0.0", + "react-dom": "^19.0.0" + } + }, + "examples/interactive-demo/node_modules/@prauga/flexdoc-client/node_modules/lucide-react": { + "version": "0.525.0", + "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.525.0.tgz", + "integrity": "sha512-Tm1txJ2OkymCGkvwoHt33Y2JpN5xucVq1slHcgE6Lk0WjDfjgKWor5CdVER8U6DvcfMwh4M8XxmpTiyzfmfDYQ==", + "license": "ISC", + "peerDependencies": { + "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" + } + }, "examples/interactive-demo/node_modules/lucide-react": { "version": "1.38.0", "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.38.0.tgz", @@ -166,6 +238,32 @@ "typescript-eslint": "^8.68.0" } }, + "examples/nestjs/node_modules/@prauga/flexdoc-backend": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@prauga/flexdoc-backend/-/flexdoc-backend-3.4.0.tgz", + "integrity": "sha512-wQG1t1dKvYy5GAvjuePehr5CXQq1M7QUTQExT4fxMlLIOq9TiFAmL4sMPVsldlXc5MelUwxvCW/8Vi/khJ7F2g==", + "license": "AGPL-3.0-or-later", + "dependencies": { + "jsonwebtoken": "^9.0.2", + "tldts": "^7.4.11", + "yargs": "^17.7.2" + }, + "bin": { + "flexdoc-auth-generator": "dist/scripts/generate-auth.js" + }, + "peerDependencies": { + "@nestjs/common": "^10.0.0 || ^11.0.0 || ^12.0.0", + "@nestjs/core": "^10.0.0 || ^11.0.0 || ^12.0.0" + }, + "peerDependenciesMeta": { + "@nestjs/common": { + "optional": true + }, + "@nestjs/core": { + "optional": true + } + } + }, "node_modules/@adobe/css-tools": { "version": "4.5.0", "resolved": "https://registry.npmjs.org/@adobe/css-tools/-/css-tools-4.5.0.tgz", From ef660291a1798e69895c86579114d2c62fae6a30 Mon Sep 17 00:00:00 2001 From: Vishnu R Date: Tue, 22 Sep 2026 22:09:29 +0530 Subject: [PATCH 3/3] docs: state the 3.5.0 behavior break and Apache-2.0 publication 3.5.0 changes the default validation result inside the 3.x range, and it is the first client, backend, and CLI release whose package metadata is Apache-2.0. The notes say both, and they do not rewrite tarballs already on the registry. Signed-off-by: Vishnu R --- CHANGELOG.md | 8 +++++--- docs/releases/3.5.0.md | 14 +++++++++++--- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 678c2ad3..83100b7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,13 +2,15 @@ Notable FlexDoc product releases are recorded here. Detailed release notes remain under `docs/releases/` and are linked from each entry. -## Unreleased - ## 3.5.0 — Node disagreement loop `@prauga/flexdoc-client` and `@prauga/flexdoc-backend` **3.5.0**, with `@prauga/flexdoc-cli` **0.8.0**. Native adapter versions are unchanged. -- An implemented route that OpenAPI does not document fails `flexdoc validate` when runtime discovery is complete, and the failure names the method and path. Partial discovery keeps that finding a warning. A service that previously passed validation with only that warning now fails the default check. +**Behavior change.** The 3.x line is not strict SemVer. `^3.4.0` can resolve to 3.5.0, and a service that previously passed validation with only an undocumented-route warning now fails the default check. + +**Licensing.** This release publishes the client, backend, and CLI under Apache-2.0. The 3.4.0 client and backend packages, and CLI 0.7.0, recorded `AGPL-3.0-or-later`. The new license applies to these artifacts and does not replace tarballs already on the registry. + +- An implemented route that OpenAPI does not document fails `flexdoc validate` when runtime discovery is complete, and the failure names the method and path. Partial discovery keeps that finding a warning. - `runtimeIntelligence.acknowledgedUndocumented` records a chosen route as acknowledged info. The route stays registered, `summary.runtime` still counts it, and the acknowledgement does not fail validation. - Opening that finding shows the missing contract beside the registered method and path, and can send it from the API Client. The URL uses the snapshot `serverOrigin` when present, and is same-origin otherwise. The request asks to prefer the API host only when host execution is available and the server has not opted out. diff --git a/docs/releases/3.5.0.md b/docs/releases/3.5.0.md index 9642dcfa..9eb46176 100644 --- a/docs/releases/3.5.0.md +++ b/docs/releases/3.5.0.md @@ -2,6 +2,16 @@ FlexDoc **3.5.0** publishes the Node disagreement loop. Package semver stays independent of product-milestone labels. +## Behavior change + +**This is not a backwards-compatible minor.** The 3.x package line is not strict SemVer. A dependency written as `@prauga/flexdoc-backend` `^3.4.0` can resolve to 3.5.0 on a fresh install, and a service that previously passed validation with only an undocumented-route warning then fails the default check without a configuration change. That failure is the point of the release. + +When runtime discovery is complete, an implemented route that OpenAPI does not document is an error. `flexdoc validate` exits 1 and names the method and path. Partial discovery keeps that finding a warning. + +## Licensing + +`@prauga/flexdoc-client`, `@prauga/flexdoc-backend`, and `@prauga/flexdoc-cli` are published under Apache-2.0 in this release. The 3.4.0 client and backend packages, and CLI 0.7.0, recorded `AGPL-3.0-or-later` in their package metadata. Apache-2.0 applies to the artifacts published from this release. It does not replace tarballs already on the registry. + ## Package versions - `@prauga/flexdoc-client` — **3.5.0** @@ -10,9 +20,7 @@ FlexDoc **3.5.0** publishes the Node disagreement loop. Package semver stays ind `@prauga/flexdoc-core` and the native adapter lines are unchanged. This wave does not change their behavior. Examples and the install tables stay on the artifacts a user can install today, and move to these versions in the post-publish repin. -## What changes for an existing Node service - -When runtime discovery is complete, an implemented route that OpenAPI does not document is an error. `flexdoc validate` exits 1 and names the method and path. Partial discovery keeps that finding a warning. A check that previously passed because the only disagreement was that warning now fails. +## What the loop does `runtimeIntelligence.acknowledgedUndocumented` marks a chosen route as acknowledged info. The route remains in the runtime record, `summary.runtime` still counts it, and the acknowledgement does not fail validation.