Background
#123 added OpenAPI markdown generation via an apidocs script in all three services:
"apidocs": "npx widdershins --language_tabs 'javascript:JavaScript:request' 'javascript--nodejs:Node.JS' --summary openapi.json -o openapi.md"
widdershins is not a declared dependency, so npx resolves and downloads it from the registry on every run. Since build now chains apidocs (lb-tsc && npm run openapi-spec && npm run apidocs) — and pretest → rebuild → build — this means every npm run build, npm test, and the Docker RUN npm run build now depends on a network fetch of an unpinned, floating version.
Problems:
- Non-reproducible builds (picks up new widdershins releases silently →
openapi.md output can change).
- Breaks on offline / air-gapped CI or a registry hiccup, and adds latency on clean environments.
- A bad widdershins release would break the build of all three services.
Fix
Pin widdershins as a devDependency (the version that generated the committed docs is 4.0.1 — see Generator: Widdershins v4.0.1 in the existing openapi.md) and call the local bin instead of npx, in services/{orchestrator,subscription,tenant-management}-service/package.json:
Then npm install to lock it.
Optional (same area)
- Consider moving doc generation out of
build into a dedicated docs script + a CI drift-guard (npm run docs --workspaces && git diff --exit-code services/**/openapi.{json,md}) so doc-gen failures don't fail compile/test and Docker builds stay offline-safe.
- orchestrator's
openapi.json info.title is the package name (@sourceloop/ctrl-plane-orchestrator-service) — set a human title to match the tenant/subscription fix.
Acceptance
widdershins is a pinned devDependency in all three services; lockfile updated.
apidocs no longer uses npx.
npm run build works with no network access to the npm registry for widdershins.
Follow-up to #123 (merged with these as non-blocking review comments).
Background
#123 added OpenAPI markdown generation via an
apidocsscript in all three services:widdershinsis not a declared dependency, sonpxresolves and downloads it from the registry on every run. Sincebuildnow chainsapidocs(lb-tsc && npm run openapi-spec && npm run apidocs) — andpretest → rebuild → build— this means everynpm run build,npm test, and the DockerRUN npm run buildnow depends on a network fetch of an unpinned, floating version.Problems:
openapi.mdoutput can change).Fix
Pin
widdershinsas a devDependency (the version that generated the committed docs is 4.0.1 — seeGenerator: Widdershins v4.0.1in the existingopenapi.md) and call the local bin instead ofnpx, inservices/{orchestrator,subscription,tenant-management}-service/package.json:Then
npm installto lock it.Optional (same area)
buildinto a dedicateddocsscript + a CI drift-guard (npm run docs --workspaces && git diff --exit-code services/**/openapi.{json,md}) so doc-gen failures don't fail compile/test and Docker builds stay offline-safe.openapi.jsoninfo.titleis the package name (@sourceloop/ctrl-plane-orchestrator-service) — set a human title to match the tenant/subscription fix.Acceptance
widdershinsis a pinned devDependency in all three services; lockfile updated.apidocsno longer usesnpx.npm run buildworks with no network access to the npm registry for widdershins.Follow-up to #123 (merged with these as non-blocking review comments).