Migrator 4.1.0 refuses to run: bundled compat manifest still pins the migrator at 4.0.0

[cratis-stagehand]

Every @cratis/components.migrator@4.1.0 CLI fails its own compatibility preflight and exits before doing any work:

$ npx --package "@cratis/components.migrator@4.1.0" cratis-components-change-handler --check ./Source
Compatibility preflight failed: Bundled compatibility manifest has stale migrator package metadata.

Expected the codemod to report what it would rewrite. Instead nothing runs — this affects cratis-components-change-handler, cratis-components-button-variant-tone, and cratis-components-remove-root-namespace-imports alike, since they all share lib/compatibility.js.

Cause

compat-manifest.json bundled in the 4.1.0 tarball still carries the 4.0.0 entry:

{ "name": "@cratis/components.migrator", "role": "migrator", "version": "4.0.0",
  "releaseMajorRange": ">=4 <5", "independentRelease": false, ... }

while package.json says "version": "4.1.0". lib/compatibility.js requires exact equality:

if (packageEntry?.version !== migratorVersion || ...) {
    throw new Error('Bundled compatibility manifest has stale migrator package metadata.');
}

toolingCompatibility.migrator is >=4 <5 and passes; it is only the packages[] entry's pinned version that fails. So the manifest is not regenerated (or not re-pinned) as part of cutting a release, and the check is exact rather than range-based — which means the same breakage recurs on every future release.

@cratis/components.migrator@4.0.0 runs fine, so the workaround is to pin the older version.

Why it matters

The migrator is the tool the 3 → 4 migration guide points people at for the Dropdown onChange → ChangeHandler<T> change and the Button variant/tone cleanup. Every consumer upgrading to the current Components release hits a preflight failure with no indication that an older migrator would work, so it reads as "the migration tooling is broken" rather than "pin 4.0.0". Found while migrating Cratis/Stagehand to Components 4 (Cratis/Stagehand#356); we did the 23 Dropdown call sites by hand.

[cratis-stagehand]

Investigation

Investigation summary

Reproduced — against the real published tarball, not by reading code.

$ npm pack @cratis/components.migrator@4.1.0
$ node -e "…"
package.json version:              4.1.0
manifest migrator entry version:   4.0.0

$ ./node_modules/.bin/cratis-components-change-handler --check ./App.tsx
Compatibility preflight failed: Bundled compatibility manifest has stale migrator package metadata.   EXIT=1

All three binaries fail identically. @cratis/components.migrator@4.0.0 against a Components 4.1.0 install works (1 would change). Patching only the manifest's packages[].version to 4.1.0 inside the 4.1.0 tarball makes 4.1.0 work — so the code is fine and only the packaged manifest is wrong.

Root cause is release-time drift, and it is wider than the migrator. @cratis/components@4.1.0 ships the same stale manifest — every one of its seven packages[] entries says 4.0.0. The migrator is simply the only package that enforces its manifest at runtime (Migrator/lib/compatibility.js:99).

The mechanism, at run-task-on-workspaces.js:107-125: publish-version <v> rewrites each public workspace's package.json to the release version and immediately npm publishes it, in one loop. The three checked-in compat-manifest.json copies (root, Source/, Migrator/) are generated by scripts/generate-compat-manifest.mjs from those same package.json versions, but that generator is never run in .github/workflows/publish.yml — the publish job only does prepare && build && publish-version. In the repo, versions and manifest agree at 4.0.0 and yarn verify-compat-manifest passes; the divergence exists only in the ~30 seconds between the version bump and the publish, which nothing observes.

This recurs on every release, exactly as the reporter says. It did not bite on 4.0.0 only because the checked-in manifest happened to already say 4.0.0.

Why no test caught it: Migrator/test/verify-packed-package.mjs does pack the real tarball and call validateBundledManifest, but it packs from the source tree, where the two always agree. No test exercises the post-bump state.

Fix validated locally: copied the repo, bumped all public workspaces to 4.1.0, ran generate-compat-manifest --write, then validateBundledManifest(manifest, '4.1.0') → passes, migrator entry 4.1.0.

SUGGESTED-MODEL: sonnet

Plan

Settled — do not re-litigate

• The bug is confirmed against the published artifact; no further reproduction needed.
• The migrator's transform code is not implicated. Only packaging is.
• scripts/generate-compat-manifest.mjs already produces a correct manifest for any release version; it does not need new logic, only to be invoked at the right moment.
• The drift affects all seven packages, not just the migrator.

1. Regenerate the manifest during release (the actual fix)

Split run-task-on-workspaces.js publish-version into two passes instead of the current bump-and-publish-per-workspace loop:

1. Pass 1 — rewrite every public workspace package.json to the release version (existing preparePackageForRelease), writing all of them before anything is published.
2. Then run scripts/generate-compat-manifest.mjs in --write mode, followed by --check, so the three manifest copies are rebuilt from the just-bumped versions and asserted deterministic. Fail the publish if either step fails.
3. Pass 2 — npm publish each workspace.

Extract steps 1–2 into scripts/prepare-release-version.mjs exporting a pure-ish function taking a root directory and a version, so it is unit-testable. Keeping the whole thing inside yarn publish-version (rather than adding a step to publish.yml) means the workflow_dispatch manual-recovery path documented in release.md is covered too.

Note for the implementer: validateCompatibilityManifest hard-codes >=4 <5 per package in packagePolicies, so wiring generation into publish means a 5.0.0 release will fail the publish until those ranges are updated. That is the desired fail-closed behavior, but call it out in release.md so it is not a surprise at the 5.0 cut.

2. Regression coverage

• In scripts/generate-compat-manifest.test.mjs (node:test style, matches the existing file): build a temp copy of the workspace manifests at a version different from the checked-in one, run the release preparation, and assert every packages[].version equals it and validateBundledManifest(manifest, version) passes. This is the test that would have caught 4.1.0.
• In Migrator/test/verify-packed-package.mjs, add a case that packs from a temp tree bumped to a synthetic version and asserts the CLI still passes preflight — the end-to-end version of the same guarantee.

3. Improve the failure message (Migrator/lib/compatibility.js:99-110)

Keep the exact-equality check — it is the only thing that caught a broken release, and range-based comparison would have let 4.1.0 ship silently and let a genuinely mismatched manifest through. Instead make the message diagnostic:

Bundled compatibility manifest pins @cratis/components.migrator at 4.0.0 but this package is 4.1.0. This is a packaging defect in this migrator release, not a problem with your project. Use a migrator version whose manifest matches, or report it at https://github.com/Cratis/Components/issues.

Update Migrator/test/compatibility.test.js's rejects stale bundled migrator metadata assertion accordingly.

4. Release and follow-up

• Ship as a patch release (the fix corrects packaging behavior consumers observe). Once 4.1.1 is out, the migration guide's TOOLING_RANGE="^4.0.0" resolves to it and the documented path works again with no doc change.
• Documentation/Migration/3-to-4.md:124 describes the preflight as a safety feature; consider one sentence saying a preflight failure naming a manifest/version mismatch is a tooling defect to report, not a project problem.

Needs a human decision

1. Deprecate @cratis/components.migrator@4.1.0 on npm? (npm deprecate … "Broken compatibility preflight; use 4.1.1 or later") — an outward-facing registry action I should not take unprompted. @cratis/components@4.1.0 itself is fine and should not be deprecated.
2. Relaxing the check — the reporter suggests range-based comparison. I recommend against it for the reason above, but if the owners prefer the migrator to be tolerant of its own manifest, that changes the shape of item 3.
3. Scope: whether to fix only the release pipeline (items 1–2) or also land the message and doc changes (items 3–4) in the same PR. They are related enough for one PR under the "group small related changes" rule.

Suggested model for implementation: sonnet

---

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

[cratis-stagehand]

Investigation

All facts in the prior investigation check out against the current repo state: run-task-on-workspaces.js's publish-version task (lines 108–126) bumps and publishes per-workspace with no manifest regeneration step; .github/workflows/publish.yml's publish-npm-packages job runs only prepare && build && publish-version, never generate-compat-manifest; the root ci script does run verify-compat-manifest, but that only ever sees the pre-bump, in-repo state (currently 4.0.0 everywhere, consistent). Migrator/lib/compatibility.js:98-109's exact-equality check is confirmed as written. The test files named in the plan (scripts/generate-compat-manifest.test.mjs, Migrator/test/verify-packed-package.mjs, Migrator/test/compatibility.test.js) all exist as described. The prior plan's mechanism, root cause, and proposed fix remain accurate and require no changes.

SUGGESTED-MODEL: sonnet

Plan (confirmed against current repo state — no changes needed to the prior investigation)

Settled — do not re-litigate

• Bug reproduced against the published tarball (not just code reading); confirmed again by re-reading the exact mechanism in the current source tree.
• The migrator's transform code is not implicated — packaging only.
• run-task-on-workspaces.js:108-126 (publish-version) bumps package.json and publishes in the same loop, per workspace, with no manifest step in between.
• .github/workflows/publish.yml's publish-npm-packages job runs yarn workspace @cratis/components prepare && yarn build && yarn publish-version "$RELEASE_VERSION" — confirmed no generate-compat-manifest invocation anywhere in that job.
• scripts/generate-compat-manifest.mjs already produces a correct manifest for any release version; it needs no new logic, only to run at the right moment.
• The drift affects all seven public packages, not just the migrator (packagePolicies in generate-compat-manifest.mjs:20-28).
• In-repo state is currently consistent (all packages at 4.0.0 in compat-manifest.json and each workspace's package.json), which is exactly why yarn ci's verify-compat-manifest step passes today and would keep passing right up to the moment publish-version bumps versions without regenerating the manifest.

1. Regenerate the manifest during release (the actual fix)

Split publish-version in run-task-on-workspaces.js into two passes instead of the current bump-and-publish-per-workspace loop:

1. Pass 1 — rewrite every public workspace's package.json to the release version (preparePackageForRelease, already correct), writing all of them before anything is published.
2. Then run scripts/generate-compat-manifest.mjs in --write mode, followed by --check, so the three manifest copies (compat-manifest.json, Source/compat-manifest.json, Migrator/compat-manifest.json) are rebuilt from the just-bumped versions and asserted deterministic. Fail the publish if either step fails.
3. Pass 2 — npm publish each workspace.

Extract steps 1–2 into scripts/prepare-release-version.mjs exporting a pure-ish function taking a root directory and a version, so it's unit-testable. Keep this inside yarn publish-version (rather than adding a step to publish.yml) so the workflow_dispatch manual-recovery path is covered too.

Note for the implementer: validateCompatibilityManifest's packagePolicies hard-code >=4 <5 per package, so wiring generation into publish means a 5.0.0 release will fail the publish until those ranges are updated — call this out in release.md so it's not a surprise at the 5.0 cut.

2. Regression coverage

• scripts/generate-compat-manifest.test.mjs: build a temp copy of the workspace manifests at a version different from the checked-in one, run the release preparation, assert every packages[].version equals it and validateBundledManifest(manifest, version) passes.
• Migrator/test/verify-packed-package.mjs: add a case that packs from a temp tree bumped to a synthetic version and asserts the CLI still passes preflight.

3. Improve the failure message (Migrator/lib/compatibility.js:98-109)

Keep the exact-equality check (it's what caught this). Make the message name both versions and state this is a packaging defect, not a project problem — update Migrator/test/compatibility.test.js's corresponding assertion.

4. Release and follow-up

• Ship as a patch release.
• Consider one added sentence to Documentation/Migration/3-to-4.md:124 noting that a preflight failure naming a manifest/version mismatch is a tooling defect to report, not a project problem.

Needs a human decision

1. Deprecate @cratis/components.migrator@4.1.0 on npm? — outward-facing registry action, should not be taken unprompted.
2. Relax the exact-version check to a range? Recommend against (see above), but confirm with owners.
3. Scope of one PR: pipeline fix + regression tests (items 1–2) vs. also bundling the message/doc changes (items 3–4). Related enough for one PR, but worth confirming.

Suggested model for implementation: sonnet

---

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

[einari]

The prediction held: 4.1.1 ships the same stale entry, so the current latest migrator is also dead on arrival.

$ npm pack @cratis/components.migrator@4.1.1
manifest says migrator: 4.0.0
package version:        4.1.1

Hit while migrating Cratis/Scene to Components 4. Pinning @cratis/components.migrator@4.0.0 works — all three codemods ran there (543 files scanned, nothing to change, since that repo already used explicit subpaths).