@cratis/components.primereact pins its Components peer to an exact version, contradicting its own README

[cratis-stagehand]

@cratis/components.primereact@4.1.0 declares:

"peerDependencies": { "@cratis/components": "4.1.0", ... }

while its bundled README.md states:

The adapter requires @cratis/components >=4 <5. This range is intentionally bounded to the Components major whose renderer ABI and stable presentation profile it implements.

Those two cannot both be true. The exact pin is what npm/yarn actually enforce, so a consuming application has to pin @cratis/components to 4.1.0 exactly rather than ^4.0.0, and every subsequent Components patch is a lockstep bump of both packages or a peer-dependency error.

Expected: the peer range to match the documented >=4 <5, so the adapter tracks the renderer ABI major it implements rather than one specific release.

If the exact pin is deliberate — e.g. the renderer ABI is not actually stable within the major yet — then the README claim is the thing that is wrong, and saying so explicitly would be more useful than the current contradiction, because it tells adopters to expect a coordinated bump on every release.

Found while migrating Cratis/Stagehand to Components 4 (Cratis/Stagehand#356); we pinned @cratis/components to 4.1.0 exactly to satisfy it.

[cratis-stagehand]

Investigation

Reproduced. The exact pin is not in the source — it is injected by the publish pipeline.

• Source declares the documented range: Adapters/PrimeReact/package.json:peerDependencies → "@cratis/components": ">=4 <5" (same in Adapters/Mui, Adapters/PrimeReact10, Conformance).
• run-task-on-workspaces.js:73-89 (preparePackageForRelease) rewrites every dependency-field entry whose name is a workspace package to the exact release version — and its field list includes 'peerDependencies'.
• I ran that exact function (extracted verbatim from the file, no edits to the repo) against the real Adapters/PrimeReact/package.json with version 4.1.0:
  • source: ">=4 <5" → prepared-for-publish: "4.1.0"
• That matches what npm actually serves: npm view @cratis/components.primereact@4.1.0 peerDependencies → "@cratis/components": "4.1.0"; @cratis/components.mui@4.1.0 is pinned identically.

Which side is wrong is settled by the repo itself, not by my reading: compat-manifest.json records >=4 <5 for every adapter, scripts/generate-compat-manifest.mjs:20-27 encodes it as release policy, and each adapter's scripts/verify-packed-package.mjs:126-138 fails the build unless the packed peer set is exactly '@cratis/components': '>=4 <5' — "the exact bounded adapter policy". Those gates pack from source, before publish-version rewrites the manifest, so nothing ever re-checks the artifact that is actually published. The line was added in bfb1330 ("Restore label-driven Components publishing"), a broad workflow-restoration commit whose message says nothing about peer pinning — generic Cratis version-stamping applied to a field it should not touch. The README is correct; the publish script is the defect.

SUGGESTED-MODEL: sonnet

Plan — #233

Settled (do not redo)

• Root cause is preparePackageForRelease in run-task-on-workspaces.js, not any package manifest and not the README.
• The intended peer range is >=4 <5. Do not "fix" the README, and do not change any adapter peerDependencies — they are already right.
• Scope is 4 published packages, not 1: @cratis/components.mui, .primereact, .primereact10, .conformance all declare a workspace peer and all ship pinned.
• Exact-version stamping of dependencies/devDependencies/optionalDependencies must stay — those use workspace:^, and the pipeline calls plain npm publish (not yarn npm publish), so nothing else would resolve the workspace protocol.

Implementation

1. Extract the release-preparation logic for testability. Move preparePackageForRelease into scripts/lib/prepare-package-for-release.cjs (CJS, since run-task-on-workspaces.js is CJS; scripts/lib/ already houses shared logic) and require it from the runner. Include the standard Cratis license header — note the runner itself carries /* eslint-disable header/header */, new files under scripts/ do not. (Alternative if extraction is unwanted: keep it in place, module.exports it, and guard the CLI body with require.main === module.)
2. Stop rewriting peer ranges. Keep the exact-version substitution for dependencies, devDependencies, optionalDependencies. Handle peerDependencies separately: leave an authored literal range untouched, and only substitute when the spec uses the workspace: protocol (translating workspace:^ → ^<version>, workspace:~ → ~<version>, workspace:* → <version>), so a future workspace: peer cannot leak an unresolvable spec to npm.
3. Fail loudly on an incoherent peer range. Using semver (already a root devDependency, 7.8.5), assert that the release version satisfies each retained workspace peer range and abort the publish otherwise — that is what catches the mirror-image bug (releasing 5.0.0 while adapters still say >=4 <5), which the current silent rewrite would have papered over.
4. Lock it with a test. Add scripts/prepare-package-for-release.test.mjs (node --test, matching generate-compat-manifest.test.mjs) that runs the real function over every non-private workspace manifest and asserts: version stamped; workspace:^ dev/dependency specs resolved to the exact version; peerDependencies['@cratis/components'] still >=4 <5; and that an unsatisfiable peer range aborts. Wire it into the root ci script alongside test-release-policy / test-release-evidence (package.json:43) so javascript-build.yml runs it.
5. Optional hardening (cheap, worth it): have the adapters' verify-packed-package.mjs assert the peer set against the release-prepared manifest as well, so the gate that already claims to check "the exact bounded adapter policy" actually covers the artifact consumers download.

Verification

yarn ci at the root (runs the policy tests plus each workspace's ci, including verify-package). Plus the direct repro above re-run after the fix: prepared Adapters/PrimeReact/package.json at some version must still read ">=4 <5".

Notes for the PR

• Already-published 4.1.0 cannot be corrected in place — npm metadata is immutable. The fix takes effect on the next release; consumers such as Cratis/Stagehand can relax to ^4 once that ships. Say so in the PR body so adopters know when they can unpin.
• Release label: this changes published package metadata that consumers resolve against (a widening of a peer range, non-breaking) → patch, not no-release.

Needs a human decision (non-blocking)

• Whether to cut a release immediately after merge purely to publish corrected metadata, or let it ride on the next scheduled release. The code fix is unaffected either way.

Suggested model for implementation: sonnet

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.

[cratis-stagehand]

Investigation

Every claim in the prior investigation checks out exactly: source manifests, the publish rewrite, the blame commit, the compat-manifest policy, the packed-package gate blind spot, and semver availability. Nothing needs correction. This is a confirmed, well-scoped, non-guessing plan ready for implementation.

Investigation summary — #233

Reproduced and independently re-verified. I re-ran every check from the prior investigation directly against the repo rather than trusting the write-up:

• Adapters/PrimeReact/package.json, Adapters/Mui/package.json, Adapters/PrimeReact10/package.json, and Conformance/package.json all declare "@cratis/components": ">=4 <5" in peerDependencies — confirmed by direct read.
• run-task-on-workspaces.js:73-89 (preparePackageForRelease) includes 'peerDependencies' in the field list it rewrites to the exact release version for any dependency name that matches a workspace package name.
• Ran the exact function (copied verbatim, no repo edits) against the real Adapters/PrimeReact/package.json with version 4.1.0: source >=4 <5 → prepared 4.1.0. Confirmed reproduction.
• compat-manifest.json and scripts/generate-compat-manifest.mjs:20-27 encode >=4 <5 as the release policy for every adapter package.
• Adapters/PrimeReact/scripts/verify-packed-package.mjs:126-138 asserts the packed peer set is exactly >=4 <5 and fails otherwise — but it packs from Source/Adapters directly via npm pack, before publish-version runs preparePackageForRelease, so this gate never sees the artifact that's actually published.
• git log confirms the peerDependencies field was added to the rewrite list in bfb1330 ("Restore label-driven Components publishing"), a broad workflow-restoration commit unrelated in its message to peer pinning.
• semver@7.8.5 is present as a root devDependency, and package.json:43's ci script already runs test-release-policy/test-release-evidence in the same pattern the prior plan proposes extending.

Every fact underpinning the earlier plan holds up under direct re-inspection. No part of the plan needs revision.

SUGGESTED-MODEL: sonnet

Plan — #233

Settled (do not redo)

• Root cause is preparePackageForRelease in run-task-on-workspaces.js, not any package manifest and not the README.
• The intended peer range is >=4 <5. Do not "fix" the README, and do not change any adapter peerDependencies — they are already right.
• Scope is 4 published packages, not 1: @cratis/components.mui, .primereact, .primereact10, .conformance all declare a workspace peer and all ship pinned.
• Exact-version stamping of dependencies/devDependencies/optionalDependencies must stay — those use workspace:^, and the pipeline calls plain npm publish (not yarn npm publish), so nothing else would resolve the workspace protocol.

Implementation

1. Extract the release-preparation logic for testability. Move preparePackageForRelease into scripts/lib/prepare-package-for-release.cjs (CJS, since run-task-on-workspaces.js is CJS; scripts/lib/ already houses shared logic) and require it from the runner. Include the standard Cratis license header — the runner itself carries /* eslint-disable header/header */, new files under scripts/ do not. (Alternative if extraction is unwanted: keep it in place, module.exports it, and guard the CLI body with require.main === module.)
2. Stop rewriting peer ranges. Keep the exact-version substitution for dependencies, devDependencies, optionalDependencies. Handle peerDependencies separately: leave an authored literal range untouched, and only substitute when the spec uses the workspace: protocol (translating workspace:^ → ^<version>, workspace:~ → ~<version>, workspace:* → <version>), so a future workspace: peer cannot leak an unresolvable spec to npm.
3. Fail loudly on an incoherent peer range. Using semver (already a root devDependency, 7.8.5), assert that the release version satisfies each retained workspace peer range and abort the publish otherwise — that catches the mirror-image bug (releasing 5.0.0 while adapters still say >=4 <5), which the current silent rewrite would have papered over.
4. Lock it with a test. Add scripts/prepare-package-for-release.test.mjs (node --test, matching generate-compat-manifest.test.mjs) that runs the real function over every non-private workspace manifest and asserts: version stamped; workspace:^ dev/dependency specs resolved to the exact version; peerDependencies['@cratis/components'] still >=4 <5; and that an unsatisfiable peer range aborts. Wire it into the root ci script alongside test-release-policy / test-release-evidence (package.json:43) so javascript-build.yml runs it.
5. Optional hardening (cheap, worth it): have the adapters' verify-packed-package.mjs assert the peer set against the release-prepared manifest as well, so the gate that already claims to check "the exact bounded adapter policy" actually covers the artifact consumers download.

Verification

yarn ci at the root (runs the policy tests plus each workspace's ci, including verify-package). Plus the direct repro above re-run after the fix: prepared Adapters/PrimeReact/package.json at some version must still read ">=4 <5".

Notes for the PR

• Already-published 4.1.0 cannot be corrected in place — npm metadata is immutable. The fix takes effect on the next release; consumers such as Cratis/Stagehand can relax to ^4 once that ships. Say so in the PR body so adopters know when they can unpin.
• Release label: this changes published package metadata that consumers resolve against (a widening of a peer range, non-breaking) → patch, not no-release.

Needs a human decision (non-blocking)

• Whether to cut a release immediately after merge purely to publish corrected metadata, or let it ride on the next scheduled release. The code fix is unaffected either way.

Suggested model for implementation: sonnet

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.