cmp-upgrade

cmp-upgrade — move a KMP project to a proven-green version set

Your job: turn "upgrade my KMP versions" (or "my build broke after a version bump") into a project sitting on a proven-green version set — one that is known to build on Android + iOS — without hand-editing versions one at a time. You wrap the engine's upgrade command (exposed on the CLI as the upgrade subcommand). Do not hand-edit libs.versions.toml yourself when the engine can do it — the engine diffs, guards the lockstep, writes surgically, and backs up.

Why this exists. The recurring pain of KMP is that Kotlin / KSP / Compose / Room / AGP move in lockstep or the build dies. Upgrading "just Kotlin" is how projects break: ksp must always be <kotlin>-<kspVersion> (e.g. kotlin 2.2.20 ↔ ksp 2.2.20-2.0.4), Room on iOS needs ksp.useKSP2=true, and AGP pins a minimum Gradle wrapper. A proven-green set moves all of them together — one command instead of a day of dependency archaeology.

The workflow: diff → apply → verify

# 1. DIFF (safe, writes nothing) — show what the upgrade would change:
node <repo>/bin/create-cmp.mjs upgrade --dry-run
#    (add --target-dir <dir> when not running from the project root,
#     --set <id> to target a specific registry set instead of the latest)

# 2. APPLY — after the user has seen and accepted the diff:
node <repo>/bin/create-cmp.mjs upgrade --yes

# 3. VERIFY — prove the build is green (or chain it: upgrade --yes --verify):
node <repo>/bin/create-cmp.mjs verify

(If invoked from the published package: npx create-cmp-cli@latest upgrade ….)

What the engine does when applying:

• Rewrites only the changed version values in gradle/libs.versions.toml — surgical line edits; comments, formatting, and every unrelated line are preserved byte-for-byte.
• Adds/updates the gradle.properties flags the set requires (e.g. ksp.useKSP2=true).
• Updates the Gradle wrapper distributionUrl when the set pins one.
• Rewrites compileSdk / targetSdk in composeApp/build.gradle.kts when the set pins them (its androidSdk block) — the Android SDK levels are coupled to the set (a newer AGP + newer androidx force a higher compileSdk), so the version set manages them too, not just the catalog.
• Backs up every touched file as <file>.bak-upgrade before writing and prints the exact mv commands to revert.
• Versions the project declares that the set doesn't know are left untouched (and warned), so project-specific dependencies survive.