@kentcdodds/codemod-runner

@kentcdodds/codemod-runner

Intent

Give every Kody user a safe, repeatable way to apply their own bulk source transforms ("codemods") across their own saved packages — rename an export everywhere, migrate off a deprecated helper, rewrite import paths — without hand-editing each package and without risking work they cannot undo. The runner composes only public Kody capabilities (repo sessions, checks, publish, package storage), so it is also a reference for building migration-grade tooling in userland.

What it does

• Scan — run a codemod's detect over your packages and report which need it (read-only, paged)
• Dry-run — transform in throwaway repo sessions, run real publish checks, return diffs; publishes nothing; verifies idempotency
• Apply — same gates as dry-run, then snapshot each original tree and republish the transformed tree (requires a completed dry-run for the same codemod first)
• Revert — restore pre-codemod trees from ledger snapshots; skips packages republished since apply (drift)
• Runs — read the run ledger (summaries or one full run with statuses, findings, checks, diffs)
• Contract — shared types/helpers for authoring a codemod package

A codemod is a package you own that exposes an export (default name codemod) whose default export handles detect and transform. Transforms must be pure, deterministic, and idempotent. When a file cannot be transformed confidently, leave it untouched and report needsManual.

The runner uses throwaway repo sessions, never your active editing sessions, and skips packages whose repo HEAD differs from the published commit.

Prerequisites / setup

1. No user secrets. You need saved packages you own and a codemod package that implements the contract (kodyId + explicit specifier).
2. Always dry-run (and read the diffs) before apply. Keep the apply runId — revert needs it.
3. Prefer paging (runId + cursor until nextCursor is null). For large fleets, drive the loop from a durable workflow rather than one interactive call.
4. Agents: see AGENTS.md for import paths, smoke/dry-run snippets, and fleet edge cases.

Done when

• You can author or point at a codemod that passes contract validation
• scan / dry-run complete for a canary packageIds slice with readable diffs
• apply only after a completed dry-run; revert restores from the ledger when needed
• Failed checks / drift skips are reported, never silently published over in-flight work