feat(codemods): add an upgrade CLI backed by a migration catalogue

[mfal]

Publishes @mittwald/flow-codemods as a CLI and turns the migration guide into generated output of a machine-readable catalogue.

What this adds

npx @mittwald/flow-codemods@latest upgrade [revision]
npx @mittwald/flow-codemods@latest <id> [path]
npx @mittwald/flow-codemods@latest list [revision] [--json]

upgrade bumps every Flow dependency to a resolved target, installs, runs the codemods the crossed version range calls for, and ends by listing the migrations no codemod covers.

revision is patch | minor | major | a dist-tag | an exact version, default minor. The keyword bounds the target; the entry set then falls out of an exact-version gate against it (see below). Keyword resolution excludes prereleases, so upgrade minor never drifts onto the next line — only an explicit dist-tag or version reaches a -next.N.

It refuses to run on a dirty working tree unless --allow-dirty, because -y is implied when stdin is not a TTY (CI, agent runs) and an unattended run would otherwise blend its own uncommitted work into the codemod diff. --dry writes nothing and installs nothing.

list changes nothing, and has two forms. Bare, it prints the whole catalogue — offline, with no manifest and no network, so it answers in an empty directory. Given a revision, it reads the current version from package.json and shows exactly the range upgrade <revision> would act on, which makes it a dry run of the upgrade rather than a separate thing to learn. --json for an agent.

It takes a revision rather than --from/--to because --from asks for something the project already knows.

The catalogue

packages/codemods/src/migrations/<id>/entry.md is now the single source for all 23 consumer migrations. packages/components/MIGRATION.md — which ships in the flow-react-components tarball — and src/migrations.generated.ts are generated from it, so the guide and the data cannot drift apart.

Each entry carries the instruction as prose (apply) plus, where the change is mechanically decidable, a codemod. That is 10 of the 23. The other 13 are executable by hand or by an agent from the instruction alone, without reading 18 KB of guide.

Two orthogonal fields decide when an entry applies and what it costs:

field	values	decides
kind	migration · deprecation	nothing — descriptive only. It is rendered as a label and tells a reader whether their code still compiles. It used to gate selection; the gate is one rule now
action	codemod · manual · none	what — none covers a behaviour change needing no edit, which an agent has to be told or it keeps looking

The deprecation half matters more than it looks: ADR 0005 §4 leaves type-level changes outside the semver guarantee, so they may ship in a patch. Without it, list on the 1.x line would return nothing.

The gate is one rule

An entry is selected when since <= target. That is all of it — current plays no part in selection.

It used to carry a lower bound (current < since) for entries needing a person, on the reasoning that you had already applied what lay behind you. Nothing records which migrations a project has performed, so that was a guess — and a bad one here, because this tool did not exist until now. On the 1.x line every catalogue entry predates 1.0.0, so a lower bound made list and upgrade report almost nothing to precisely the people who had never migrated.

current still decides how an entry is presented: each is marked new in this range or catch-up (shipped at or before your version, so you may already have done it). Re-running a codemod over its own output is a verified no-op — transformCoverage.test.ts requires a transform.test.ts beside every transform, and each of the 10 carries a "running it twice changes nothing" case. That is not the same as being harmless against code from a later era, which is a per-transform property: imports-to-package-root needed an explicit leave-alone set to earn it (see review thread). A manual step marked catch-up needs the reader's own judgement, and the legend says so rather than implying it is done.

upgrade reports how many codemods actually changed something. "10 codemods run, 0 changed anything" is itself the confirmation that nothing was outstanding.

Groundwork for an AI-assisted update

This is a step towards a migration an agent can carry out, not only a human. That intent explains several choices that otherwise look incidental:

• apply is an instruction, not a description. 13 of the 23 entries have no codemod, and today they are 18 KB of prose a reader has to search. As a field they are actionable per entry, so an agent can work through them without reading the guide.
• list [revision] --json is read-only. It answers "what does this range require of me" against the consumer's own manifest, with no writes, no install and no network beyond the registry lookup. That gives an agent a way to plan before it changes anything.
• upgrade ends by naming what no codemod covered. A codemod is not the whole migration, and a command that stayed silent about the remainder would read as "done".
• -y is implied when stdin is not a TTY, so an agent run needs no flag — and the dirty-tree refusal exists precisely because of that: unattended, it would otherwise blend its own uncommitted work into the codemod diff with no way to separate them afterwards.

Nothing here is agent-specific, and none of it is a finished feature. It is the data and the seams such a thing needs.

One transform is not a migration

to-remote-package (formerly flowRemote) ports an app onto @mittwald/flow-remote-react-components. No version range calls for it, so it has no catalogue entry and appears in neither the guide nor list — it is run deliberately, by id, and documented in the package README. catalog.test.ts names it as the one commented exception to its otherwise exact transform-set invariant.

What this removes

The raw-GitHub-URL delivery path, and with it the self-contained-transform rule, the composite bundler and src/composites. Transform files are renamed to their dashed catalogue ids.

URLs printed in already-published MIGRATION.md copies now 404. Accepted deliberately: doc URLs are not covered by the semver contract (ADR 0005), and those consumers are better served by npx @mittwald/flow-codemods@latest upgrade, which works from any old version because npx always fetches the current CLI.

Not a breaking change under ADR 0005 — the package was private: true, so no published package API changed.

Supersedes #2942

Its transform suite, test harness, remoteScope.ts and the migration prose it added are adopted here; they were reviewed and green. Its composite bundler is not, because the CLI runs codemods individually and reports per codemod. Close #2942 rather than merging it — merging it after this lands would conflict with every rename.

Worth knowing while reviewing

• upgrade resolves the target from the intersection of what every declared Flow dependency has published, not from one of them. Lerna publishes packages one at a time, so during a release the versions diverge for the length of the run — around 25 minutes, measured. The window is narrow and self-healing, but it is exactly when someone runs upgrade. Documented for users in Document the publish window: Flow versions diverge for minutes during a release #2974.
• The codemod runner drives jscodeshift's Runner in process rather than its CLI. Scraping the CLI's text summary is unsafe: --print writes the transformed source before the summary, so a source comment like // 42 ok beat the regex reading the count.
• Every Flow dependency moves together because flow-react-components declares flow-icons-pro as a peer at an exact version. Bumping one alone is a peer conflict. The package list is generated from the workspace, not hand-picked.

Out of scope

• packages/ext-bridge/MIGRATION.md keeps its own hand-written guide.
• Executable detect / verify checks were built and taken back out — not solid enough to ship here, and better delivered on their own.
• The ~50 lines of import-resolution logic duplicated across the transforms could now be shared, since they no longer have to run standalone. Separate change.

Verification

pnpm build clean, git diff --exit-code clean, pnpm lint clean, 250 tests. upgrade verified end to end against the real npm registry, including the dirty-tree refusal, --dry, and that codemods no longer reach into a freshly installed node_modules.

[github-actions]

🚀 Preview Deployment

Preview environments are ready:

Type	URL
docs	pr-2978.docs.review.flow-components.de
storybook	pr-2978.storybook.review.flow-components.de

Images:

• docs: ghcr.io/mittwald/flow/docs:pr-2978
• storybook: ghcr.io/mittwald/flow/storybook:pr-2978

[mfal]

Blocked on #2980. The version-contract check fails here because it reads adding engines.node to a previously private package as a tightening — and neither remedy it offers is available: a breaking marker would be rejected by the routing guard on next, and dropping the floor would publish a CLI without one while its code needs Node 24.

The one-line fix was on this branch and I have reverted it out: it is CI infrastructure, a reviewer of this CLI should not have to review it, and the squash-merge would land it under a codemods commit message. #2980 carries the diff and the two tests.

[mfal]

The guard fix is now #2982, targeting main. Once it merges, the forward-merge cascade carries it to next and this PR's version-contract check goes green — no CI infrastructure needs to ride along in here.

[Lisa18289]

Reviewed by checking out the branch: build clean, git diff --exit-code clean, eslint clean, 246 tests green. Ran the built binary against temp projects and the real registry.

The architecture is right — catalogue as single source, generated MIGRATION.md, resolveRange shared between list and upgrade, driving jscodeshift's Runner instead of scraping its CLI, resolving from the intersection of published versions. Three things I'd want resolved before merge.

1. upgrade breaks correct, current code.

Selection has no lower bound, so imports-to-package-root (since: 0.2.0-alpha.28) runs on every 1.x project. The transform's else branch is a catch-all and it knows only four subpaths, so every subpath that exists in today's exports map is flattened onto the package root:

import "@mittwald/flow-react-components/all-layered.css";   // → import "@mittwald/flow-react-components";  (stylesheet silently dropped)
import { Rule } from ".../mittwald-password-tools-js";       // → from "@mittwald/flow-react-components";
import { Button } from ".../flr-universal";                  // → from "@mittwald/flow-react-components";
import { something } from ".../internal";                    // → from "@mittwald/flow-react-components";

Default imports also become named specifiers. On a clean 1.0.0 project whose only Flow line is a correct mittwald-password-tools-js import, upgrade --dry reports imports-to-package-root: 1 file(s) changed / 10 codemods run, 1 changed something.

Idempotency doesn't cover this. It proves "running the same transform twice changes nothing", not "an era-specific transform is harmless against code from a later era". Either era-scoped entries need an upper bound (until), or this transform needs an allowlist of the subpaths that existed at alpha.28 instead of the catch-all else.

2. The run order lets one migration cancel another.

selectEntries sorts ascending by since, so imports-to-package-root (alpha.28) runs before password-tools-subpath-renamed (alpha.1000). The first flattens …/password-tools onto the root; the second then finds nothing:

password-tools-subpath-renamed: 0 file(s) changed, 1 unchanged.
→ import { Rule } from "@mittwald/flow-react-components";

The root doesn't export Rule. The migration meant to fix exactly this reports success, and the aggregate reads "10 codemods run, 1 changed something".

3. First publish of a new package name under trusted publishing.

@mittwald/flow-codemods was private: true and does not exist on npm. publish.yml publishes via npm Trusted Publisher OIDC with provenance, which is configured per package — the comment at the top of that workflow describes this failure class. lerna publish from-package --concurrency 1 would abort mid-release, with the packages ahead of it already published. This needs an npm-side bootstrap before merge.

Should still go in

• hasUncommittedChanges fails open too widely: exit 128 is not only "not a repository" — detected dubious ownership is 128 too, and that's exactly the minimal CI container the guard is written for. Check git rev-parse --is-inside-work-tree first, or read stderr instead of ignoreing it.
• nx wiring: codemods:build writes packages/components/MIGRATION.md, which sits inside components-src's default glob, with no dependency edge between the two projects. Under nx run-many --targets=build nothing decides whether components:build is hashed before or after that rewrite. Exclude MIGRATION.md from components-src, or add the edge.
• engines: ">=24.0.0" on a consumer-facing CLI. The repo needs 24, consumers don't — the whole suite runs on Node 22. Anyone on 20/22 gets EBADENGINE from npx.
• peerDependencies are rewritten too. A library declaring peerDependencies: { "@mittwald/flow-react-components": "^1.0.0" } gets ^1.0.14, narrowing what its consumers may install. Intended?

Smaller

• kind has no effect on anything. Its only read is the label in list.ts:187; since the lower bound is gone, migration and deprecation behave identically. The table in the description ("decides when") describes code that isn't there.
• Stale numbers in the description and in ADR 0006: 23 entries not 22, 10 codemods not 9, 246 tests not 222. The description also cites idempotency.test.ts, which no longer exists — transformCoverage.test.ts only asserts a transform.test.ts file is present, not that it contains an idempotency case (all 10 do today).
• Out of scope for this PR: .superpowers in .gitignore/.prettierignore, the rewritten cross-version row in AGENTS.md, the CONTRIBUTE.md docs-authoring section (feat(docs): consolidate component tabs into a single page #2730).
• Comment density: list.ts carries ~140 comment lines over 280 lines of code, cli.ts opens with 12 lines on stdout-vs-stderr. Much of it is decision rationale that belongs in the ADR or the commit body.
• Ctrl+C at the codemod checkbox rejects out of runUpgrade after package.json is written and installed — the user sees an inquirer error rather than "bumped and installed, no codemods run". @inquirer/prompts is also imported eagerly, so list pays for it.
• list --json carries no range metadata (current/target), so the agent-facing form can't tell which range it got.
• On the 1.x line list and list minor return the same 23 entries, all marked catch-up, so "exactly the range upgrade would act on" is currently indistinguishable from browsing the catalogue.

The error messages are genuinely good — "minor" looks for the highest published stable release in 0.x; none is published. Use "major" (→ 1.0.14) is the kind of message one hopes for.

[mfal]

Reproduced all three blockers before touching anything. 1 and 2 are fixed in 36cbd48c4; 3 is real and not fixable in the repo.

1 + 2 have one cause, so one fix. Both come from imports-to-package-root's catch-all else. It now carries an explicit leave-alone set: every subpath the package still exports, plus password-tools, which password-tools-subpath-renamed owns. Verified both directions — current code is 0 file(s) changed, era code still migrates (/Button → root, globals.css → all.css, react-hook-form/useFoo → react-hook-form), and the rename now finds its path instead of the flatten having eaten it.

Two independent tests pin it, one comparing the set against the real exports map; removing a single entry fails both. I chose the intrinsic guard over an until bound because applicability here is a property of the code, not of the target version: a consumer genuinely on alpha.20 still needs this transform, and an upper bound keyed on the target would deny it to them.

You're right that idempotency could never have caught this — and worse, a comment in manifest.ts leaned on it as if it could. Corrected there and in the PR description.

3 stands and is yours. Confirmed: @mittwald/flow-codemods is E404 on the registry, publish.yml runs lerna publish from-package --yes --concurrency 1, and the workflow's own header documents that npm binds one Trusted Publisher per package. Nothing in the repo fixes it — the new name needs an npm-side bootstrap before this merges, or the next release aborts mid-run with the packages ahead of it already published. Worth noting no Flow package declares publishConfig, so access is handled elsewhere and adding one here would be noise.

Fixed from the rest: the git 128 guard now matches the message with LC_ALL=C pinning it, not the exit code. peerDependencies are reported and left alone, through one reporter --dry shares. MIGRATION.md excluded from components-src. Ctrl+C at the prompt reports what already happened instead of throwing an inquirer trace, and @inquirer/prompts loads lazily so list no longer pays for it. list --json now carries range plus per-entry catchUp — this replaced a test that pinned the bare array, which recorded the old shape rather than defending it. kind is descriptive; its docblock and the description's table said otherwise, both corrected, field kept because it tells a reader whether their code compiles today. Numbers and the idempotency.test.ts reference fixed in the description and the ADR.

One correction. CI runs Node 24, not 22 — prepare-workspace and every workflow pin node-version: 24, and there is no .nvmrc. Your point stands regardless: >=24.0.0 on a package reached through npx is a consumer-facing defect. The only thing needing 24 was an import attribute for reading the version, now a readFileSync; the floor is >=22.0.0. Flagging that I could not test it — this machine has only Node 24 — so 22 is reasoned from the feature set (toSorted is the highest bar), not measured. If you want it earned, a Node 22 leg on the codemods unit tests would do it.

On the out-of-scope three: all deliberate, and two exist because of this PR's timeline rather than despite it. The cross-version row and the CONTRIBUTE docs section were both wrong when I found them — #3006 landed the PR-gated iframe harness under this branch's feet and left the "not on pull requests" claim behind, and #2730's tab consolidation left CONTRIBUTE telling contributors to create three files that no longer exist. Happy to split them into their own PR if you'd rather review them separately; .superpowers I'll defend, the branch's tooling writes there.

Comment density: agreed, and list.ts is the worst of it. Say the word and I'll do a pass moving the decision rationale into the ADR; I left it for now because it is the kind of change that is easier to review on its own.

Not addressed, by choice: that list and list minor coincide on the 1.x line. That is the gate having one rule, which is deliberate — every entry predates 1.0.0, so any revision selects all of them. It resolves itself as soon as anything ships with a 1.x since.

🤖 Addressed by Claude Code