feat(sync): stop before the merge when upstream changed its sync config, add migrate --run

[flipvh]

The CLI side of raak's and projectcampus's feedback on their syncs to cella 0.16.0. The template side is cellajs/cella#1312.

Sync config is checked before the merge

cella/cella.config.ts never syncs, and the merge runs on the app's lists as they stand. Both apps received paths upstream had newly ignored (upstream renamed an ignored folder, the apps' lists still named the old one), and the report that names such entries came after the merge.

• A new merge now compares upstream's sync config from the last sync point first. With entries the app's config does not follow, the run prints them and stops before anything merges. --keep-config merges with the config as it stands (also on forks). analyze still only reports, and the rerun that commits a staged merge is not checked.
• settings.packageJsonSync is part of the comparison. Replayed on projectcampus's config from before its sync, the report now holds all six entries it had to find by hand, exports included.

This changes what an unattended cella sync does: it exits 1 where it used to merge.

A stop before the merge leaves nothing behind

• Every stop before the merge (this check, the CLI version check, a --ref that does not resolve, an unreachable upstream) removes the temporary cella/sync/* branch and returns to the starting branch. Before, the empty branch stayed checked out.
• An upstream release or branch behind the last sync point ends as a no-op with exit 0. A --ref behind it is still refused. analyze still reports it as an error.

Reports

• The protected-but-behind lists of analyze and sync end with one git diff <last-sync>..<upstream> -- <entry> line per pinned or ignored entry. An e2e test runs the printed command and checks it shows upstream's change without the app's.
• ignored entry not found only warns when the path is in neither the app nor upstream (read at the upstream branch as last fetched). An app ignores some paths to keep them from arriving, and every run warned about those.

migrate --run <id> [-- <args>]

A codemod's roots cover template-owned files, and one rewrote a file upstream had changed after writing the codemod. --run extracts the note, runs its codemod with tsx from the app root, and gives every file the codemod changed that was byte-identical to the last synced upstream commit its upstream content back. Without arguments the codemod gets inventory and the note's roots, the report-only run: all eight codemods in cella take that subcommand first. --script <file> names the script when a folder holds several.

The legacy notes folder

projectcampus reported that a conflicted first run kept the old { "applied": [...] } record and its cella/migrations/ copy. Its lockfile shows that merge ran on CLI 0.2.3, which predates this code. The new e2e test covers that path on the current code: conflicted run from the legacy state, upstream changing and deleting existing note files in range. It passes on main unchanged, so no fix was needed.

Verification

• pnpm lint, pnpm ts: clean. pnpm test: 26 files, 271 tests pass (24 files, 236 tests before). pnpm test:release: 1 passes.
• The --run example from the README was run in a sandbox app with a copy of the real tailwind note: it rewrote the app's file and restored the template's.
• Not run against a real raak or projectcampus checkout. forks --keep-config has a parse test only.

After the release

cella can then require this version in its root package.json (the version check makes apps install it before their next sync) and point its migrate skill at --run.

🤖 Generated with Claude Code