diff --git a/CHANGELOG.md b/CHANGELOG.md index efc73c28..83100b7f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,11 +2,20 @@ 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 -- 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. +`@prauga/flexdoc-client` and `@prauga/flexdoc-backend` **3.5.0**, with `@prauga/flexdoc-cli` **0.8.0**. Native adapter versions are unchanged. + +**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. +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..9eb46176 --- /dev/null +++ b/docs/releases/3.5.0.md @@ -0,0 +1,37 @@ +# FlexDoc package release 3.5.0 + +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** +- `@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 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. + +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..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", @@ -12052,7 +12150,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 +12188,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" },