@cellajs/cli 0.4.2 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @cellajs/cli
 
-Keep your app in sync with upstream [cella template](https://github.com/cellajs/cella) updates while preserving your
+Upgrade your app with upstream [cella template](https://github.com/cellajs/cella) changes while preserving your
 customizations.
 
 ## Usage
@@ -9,7 +9,7 @@ From your monorepo root, run `pnpm cella` for the interactive menu, or call a se
 
 ```bash
 pnpm cella analyze
-pnpm cella sync
+pnpm cella upgrade
 pnpm cella audit
 ```
 
@@ -17,12 +17,12 @@ pnpm cella audit
 
 | Service | Description |
 |---------|-------------|
-| `analyze` | Dry run to see what would change on sync. It leaves your files and branches alone but updates git metadata: it fetches upstream and writes `refs/cella/last-sync` and a graft for the sync base |
-| `sync` | Merge upstream changes onto a fresh branch, sync package.json and open a squash-merge PR into `main` |
-| `migrate` | List the upstream migration notes this app has not handled yet, read them, run their codemods, record them |
+| `analyze` | Dry run to see what would change on upgrade. It leaves your files and branches alone but updates git metadata: it fetches upstream and writes `refs/cella/last-upgrade` and a graft for the upgrade base |
+| `upgrade` | Merge upstream changes onto a fresh branch, merge package.json and open a squash-merge PR into `main` |
+| `align` | List the upstream alignments this app has not handled yet, read them, run their codemods, record them |
 | `audit` | Update outdated packages and runtime pins, then rebuild the security overrides from a fresh audit; report the security fixes this machine's Node, pnpm and gh miss |
 | `stats` | Count files by category and workspace package; with `--since <ref>`, count what the current branch changed, by kind of file |
-| `forks` * | Run normal sync inside local fork repositories |
+| `forks` * | Run the upgrade inside local fork repositories |
 | `contributions` * | Pull and adopt changes from local forks |
 
 \* `forks` and `contributions` only appear when you have `forks` configured in `cella.config.ts`. 
@@ -37,9 +37,9 @@ Per-service help: `pnpm cella <service> --help`.
 
 | Service | Useful options |
 |---------|----------------|
-| analyze | `--list`, `--json`, `--scope <all\|risk\|protected>`, `--track <release\|branch>`, `--ref <ref>`, `--unpinned` |
-| sync | `--track <release\|branch>`, `--ref <ref>`, `--keep-config`, `--unpinned` |
-| migrate | `--all`, `--json`, `--show <id>`, `--extract <id>`, `--run <id> [-- <codemod args>]`, `--mark <ids...>` |
+| analyze | `--list`, `--json`, `--scope <all\|risk\|protected>`, `--all`, `--track <release\|branch>`, `--ref <ref>`, `--unpinned` |
+| upgrade | `--track <release\|branch>`, `--ref <ref>`, `--keep-config`, `--unpinned` |
+| align | `--all`, `--json`, `--show <id>`, `--extract <id>`, `--run <id> [-- <codemod args>]`, `--mark <ids...>` |
 | audit | `--list` |
 | forks | `--fork <name>`, `--keep-config` |
 | contributions | `--fork <name>`, `--json` |
@@ -52,10 +52,10 @@ Per-service help: `pnpm cella <service> --help`.
 
 ## Configuration
 
-Sync behavior lives in `cella.config.ts` at your monorepo root (a sensible default ships with new
+Upgrade behavior lives in `cella.config.ts` at your monorepo root (a sensible default ships with new
 apps). To deviate files or folders from the template:
 
-- **`ignored`**: files completely excluded from sync (existing and new)
+- **`ignored`**: files completely excluded from upgrades (existing and new)
 - **`pinned`**: full fork control, existing, modified, or deleted files are preserved
 
 An `ignored` entry may name a path your app does not have, to keep it from arriving (a file upstream
@@ -69,42 +69,42 @@ to upstream, which only drops upstream's next change to it.
 
 ## Upstream tracking
 
-The sync CLI tracks upstream cella one of two ways, set via `settings.upstreamTrack`:
+The CLI tracks upstream cella one of two ways, set via `settings.upstreamTrack`:
 
 | Mode | Behavior | For |
 |------|----------|-----|
-| `release` (default) | Sync to a last cella release tag. Stable and reviewable: each bump maps to a changelog. | Most forks |
+| `release` (default) | Upgrade to the latest cella release tag. Stable and reviewable: each bump maps to a changelog. | Most forks |
 | `branch` | Follow the bleeding-edge tip of `settings.upstreamBranch`. | cella maintainers, active development |
 
 For a one-off run that ignores the configured mode, pass `--track`:
 
 ```bash
-pnpm cella sync --track branch   # follow the tip once, without editing config
+pnpm cella upgrade --track branch   # follow the tip once, without editing config
 ```
 
-To sync to one specific upstream point, pin it with `--ref` (it wins over `--track`): a commit sha,
+To upgrade to one specific upstream point, pin it with `--ref` (it wins over `--track`): a commit sha,
 a release tag or an upstream branch name, resolved on the upstream remote (`main` is upstream's
 `main`, not yours). The ref must be on `settings.upstreamBranch` or in an upstream release; a
-release tag syncs as that release, anything else is recorded like branch tracking.
+release tag upgrades as that release, anything else is recorded like branch tracking.
 
 ```bash
-pnpm cella sync --ref 4f7d87c      # sync up to this upstream commit
+pnpm cella upgrade --ref 4f7d87c      # upgrade up to this upstream commit
 ```
 
-A run never syncs to a point behind the last sync: when an earlier `--ref` or `--track branch` run
-went past the latest release, release tracking ends with a `nothing to sync` message until a newer
-release exists, instead of reverting what the app already has. A `--ref` behind the last sync is
+A run never upgrades to a point behind the last upgrade: when an earlier `--ref` or `--track branch` run
+went past the latest release, release tracking ends with a `nothing to upgrade` message until a newer
+release exists, instead of reverting what the app already has. A `--ref` behind the last upgrade is
 refused. Either way the run changes nothing and leaves you on the branch you started from.
 
-## Sync workflow
+## Upgrade workflow
 
-`pnpm cella sync` never commits to `main` directly. 
+`pnpm cella upgrade` never commits to `main` directly. 
 
 ```
-main ──▶ cella/sync/<stamp> ──(3-way merge)──▶ PR ──(squash)──▶ main
+main ──▶ cella/upgrade/<stamp> ──(3-way merge)──▶ PR ──(squash)──▶ main
 ```
 
-It runs a real git 3-way merge. `sync` is **idempotent and staged**: each run advances the sync
+It runs a real git 3-way merge. `upgrade` is **idempotent and staged**: each run advances the upgrade
 one stage, and the run that commits never ships: the pause on the committed branch is where
 drift triage (`pnpm cella analyze` diffs committed HEAD) and follow-up commits happen.
 
@@ -112,86 +112,136 @@ drift triage (`pnpm cella analyze` diffs committed HEAD) and follow-up commits h
    are reconciled (`pnpm install` + `pnpm check`), everything is staged, and the delta is
    committed; then the run stops on the branch. A conflicted merge stops earlier so you can
    resolve in your IDE (`git add` the resolved files) and re-run to commit.
-2. **Final re-run `pnpm cella sync`** on the committed branch ships it: pushes to `origin`,
-   opens a PR into `main` (via `gh`) titled like the sync commit, even with follow-up commits on
+2. **Final re-run `pnpm cella upgrade`** on the committed branch ships it: pushes to `origin`,
+   opens a PR into `main` (via `gh`) titled like the upgrade commit, even with follow-up commits on
    top, and switches you back to `main`.
 
 Before the merge starts, a first run checks that it can go ahead, and stops without changing
 anything when it cannot: the temporary branch is removed again and you are back on the branch you
 started from. It stops when upstream needs a newer `@cellajs/cli` than the one running, and when
-upstream changed its own sync config in ways yours does not follow (see
-[Upstream changes that never sync](#upstream-changes-that-never-sync)).
+upstream changed its own CLI config in ways yours does not follow (see
+[Upstream changes that never merge](#upstream-changes-that-never-merge)).
 
-`sync` also runs from a linked git worktree while another worktree has `main` checked out: it
-never switches to `main`. It compares `main` with `origin/main` by ref and cuts the sync branch
+`upgrade` also runs from a linked git worktree while another worktree has `main` checked out: it
+never switches to `main`. It compares `main` with `origin/main` by ref and cuts the upgrade branch
 from `main`; when `main` is behind and checked out elsewhere, it cuts from `origin/main` instead
 and leaves `main` as it is. After shipping, the worktree detaches at `main` instead of switching
 to it.
 
 When the commit stage runs, the in-progress merge state (`MERGE_HEAD`) is discarded, so the staged delta
-collapses into a **single-parent commit** (`chore: sync upstream cella <sha>`). This keeps the PR
+collapses into a **single-parent commit** (`chore: upgrade cella to <sha>`). This keeps the PR
 to one clean commit with the incremental diff; a two-parent merge commit would instead list the
 upstream branch's entire history, because the fork doesn't share pushed ancestry with upstream
 and the local `git replace` graft that makes merges incremental is never pushed. Ancestry lives
-in `refs/cella/last-sync` (and the committed `cella.manifest.json` for fresh clones), so
+in `refs/cella/last-upgrade` (and the committed `cella.manifest.json` for fresh clones), so
 `git merge-base` keeps working across throwaway branches; each is safe to delete once its PR
 lands. The three-segment name can't collide with git's ref namespacing.
 
-If conflicts remain when you re-run, `sync` lists them and stops (never starting a second cycle
+If conflicts remain when you re-run, `upgrade` lists them and stops (never starting a second cycle
 mid-merge). If `pnpm check`, the push, or `gh` fails, it degrades gracefully, reporting the
 issue and printing the remaining manual steps:
 
 ```bash
-git push -u origin cella/sync/<stamp>
-gh pr create --base main --head cella/sync/<stamp> --fill
+git push -u origin cella/upgrade/<stamp>
+gh pr create --base main --head cella/upgrade/<stamp> --fill
 ```
 
-## Migration notes
+## Analyze output
 
-Upstream ships a note for every change that app code has to follow, in `cella/migrations/<id>/`:
-a README (frontmatter, title, summary, then the steps) and sometimes a codemod. The notes stay
-upstream. The sync never brings that folder into the app and removes a copy it finds; `migrate`
-reads the notes from the upstream commit the app last synced to, which the sync already fetched.
+`pnpm cella analyze` prints its file sections in the order they need you: what merges on its own
+first (`behind`, `diverged`), then pinned files, drifted files, and the upstream changes the upgrade
+leaves out (`protected but behind upstream`). The summary and `next steps` close the run, so the
+last lines are the ones to act on. A file row is its path, linked per `fileLinkMode`, with a count
+and a short age (`3h`, `2d`, `3mo`) in columns.
 
-The app keeps one small record, `cella/cella.migrations.json`, listing the notes it has not
-handled yet. The sync adds the notes that arrive with it, `migrate --mark` removes them, and the
-file is deleted once the list is empty. No file means nothing is pending, so a new app starts
-without one.
+Large groups collapse: more than 15 behind files become one row per folder, more than 8 pinned files
+keep the ones missing 10 or more upstream lines, and five or more protected files of one kind under
+one override entry become one row (`backend/drizzle/ · 42 × snapshot.json`). `--all` lists every
+path.
 
-Notes are information, never a gate. Each sync run, and `analyze`, ends with one line:
+Analyze and upgrade both end with `next steps`, numbered in the order you take them: the review page,
+the command to run next, and the alignments the upgrade brings or that are still open.
 
 ```
-migration notes: 94 of 97 handled · 3 arrived with this sync · 3 open: pnpm cella migrate
+next steps
+────────────────────────────────────────────────────────────
+
+  1 review   file:///Users/you/app/.git/cella-diff/analyze-review.html
+             22 diffs in 3 sections · 42 listed without a diff
+  2 upgrade  pnpm cella upgrade
+             commits on a fresh branch, a rerun opens the PR · 36 update, 2 merge
+  3 align    1 alignment arrives with this upgrade
+             ○ Migration notes become alignments · manual · not breaking
+             after the upgrade: pnpm cella align
 ```
 
-and the sync PR lists the open notes with links. Handle them in the sync PR or later; they stay
-listed until marked.
+Without a terminal (piped, or read by an agent) each alignment row also gets its id, for
+`pnpm cella align --show <id>`.
+
+## Alignments
+
+Upstream ships an alignment for every change that app code has to follow, in
+`cella/alignments/<id>/`: a README (frontmatter, title, summary, then the steps) and sometimes a
+codemod. Alignments stay upstream. The upgrade never brings that folder into the app and removes a
+copy it finds (also of `cella/migrations/`, the migration notes upstream deleted when it started
+the alignments); `align` reads them from the upstream commit the app last upgraded to, which the upgrade
+already fetched.
+
+The frontmatter says what the change asks of the app: `breaking`, `clientCacheBump`,
+`caughtBy` (`compiler`, `tests` or `nothing`: what catches app code the change leaves behind),
+`generate` (the change needs `pnpm generate`), `grep` (words app code may still use) and, beside a
+codemod, its `roots`.
+
+The app keeps one small record, `cella/cella.alignments.json`, listing the alignments it has not
+handled yet. The upgrade adds the ones that arrive with it, `align --mark` removes them, and the file
+is deleted once the list is empty. No file means nothing is pending, so a new app starts without
+one.
+
+Alignments are information, never a gate. `analyze` and each upgrade run list them under
+[`next steps`](#analyze-output): by title, with their kind, at most five. In `analyze` the ones in
+the upgrade range *arrive with this upgrade*; they become open once the upgrade lands, which is when
+`pnpm cella align` lists them. `pnpm cella align` itself ends with one line:
+
+```
+alignments: 94 of 97 handled · 3 open: pnpm cella align
+```
+
+The upgrade PR lists the open alignments with links. Handle them in the upgrade PR or later; they
+stay listed until marked.
 
 ```bash
-pnpm cella migrate                    # open notes, with summary and links
-pnpm cella migrate --show <id>        # one note's README
-pnpm cella migrate --run <id>         # run its codemod, report only
-pnpm cella migrate --run <id> -- rewrite frontend/src   # run it with your own arguments
-pnpm cella migrate --extract <id>     # its folder under node_modules/.cache/cella/migrations/<id>/
-pnpm cella migrate --mark <id> [...]  # record notes as handled
+pnpm cella align                    # open alignments, with summary and links
+pnpm cella align --show <id>        # one alignment's README and what git tells about it
+pnpm cella align --run <id>         # run its codemod, report only
+pnpm cella align --run <id> -- rewrite frontend/src   # run it with your own arguments
+pnpm cella align --extract <id>     # its folder under node_modules/.cache/cella/alignments/<id>/
+pnpm cella align --mark <id> [...]  # record alignments as handled
 ```
 
-`--run` extracts the note and runs its codemod with `tsx` from your app root. Everything after `--`
-goes to the codemod as given; without it the codemod gets `inventory` and the note's `roots`, the
-report-only run.
+Next to its README, each alignment shows what git can tell about it: the upstream commit and PR
+that added it, the other alignments of that commit, the files of that commit the app pins, ignores
+or changed, and the lines of app code that hold one of its `grep` words. Only files that differ
+from the upstream commit of the last upgrade count, so a template file the app never touched is
+never a hit. Two or more open alignments with `generate` get one line: work their code steps first, then
+generate once. `--show` reads an alignment the last upgrade does not have yet from the fetched
+upstream branch, so it works before the upgrade that brings it.
+
+`--run` extracts the alignment and runs its codemod with `tsx` from your app root. Everything after
+`--` goes to the codemod as given; without it the codemod gets `inventory` and the alignment's
+`roots`, the report-only run.
 
 A codemod's roots cover template-owned files too, and a file that is identical to upstream already
 is the way upstream wants it: upstream may have changed it after writing the codemod, so a rewrite
 there only creates drift. Before the codemod starts, `--run` notes which files are byte-identical
-to the last synced upstream commit (`upstream.commit` in `cella/cella.manifest.json`, during a
-staged sync the incoming commit). After the run, each of those files the codemod changed gets its
+to the upstream commit of the last upgrade (`upstream.commit` in `cella/cella.manifest.json`,
+during a staged upgrade the incoming commit). After the run, each of those files the codemod changed gets its
 upstream content back, and the run prints how many it restored. Files your app changed keep the
 codemod's rewrite. The codemod's own report still counts the restored files, in a report-only run
 too. A codemod run by hand from the `--extract` folder has no such protection.
 
-## Sync rules
+## Merge rules
 
-For each file, `sync` compares fork and upstream **content** (blob comparison) and resolves it
+For each file, `upgrade` compares fork and upstream **content** (blob comparison) and resolves it
 per the table below. Unconfigured files converge on upstream; `ignored` and `pinned` let you opt
 out:
 
@@ -203,72 +253,77 @@ out:
 | Deleted in upstream | ✅ Keep | ✅ Keep | 🗑️ Delete |
 | Only in your app | ✅ Keep | ✅ Keep | ✅ Keep |
 
-**Choosing an override:** `ignored` = file never syncs and is fully hidden (app-specific docs,
+**Choosing an override:** `ignored` = file never merges and is fully hidden (app-specific docs,
 assets, config you own). `pinned` = your version always wins but stays visible (files you
-customize). Unconfigured = syncs automatically. Run `pnpm cella analyze` first to preview.
+customize). Unconfigured = merges automatically. Run `pnpm cella analyze` first to preview.
 
 ## Status indicators
 
-During analysis and sync, files are displayed with status indicators:
+During analysis and upgrade, files are displayed with status indicators:
 
 | Symbol | Label | Meaning | Action |
 |:------:|-------|---------|--------|
 | ◇ | `managed` | Package/config file changed | Handled separately by cella |
-| ⨂ | `ignored` | Protected by ignored config | Excluded from sync |
+| ⨂ | `ignored` | Protected by ignored config | Excluded from upgrades |
 | ✓ | `identical` | Fork matches upstream | No action needed |
 | ↑ | `ahead` | Fork changed (pinned), upstream did not | Protected, keeping fork |
 | ! | `drifted` | Fork changed, not protected | At risk, consider pinning |
-| ↓ | `behind` | Upstream has changes | Will sync from upstream |
+| ↓ | `behind` | Upstream has changes | Will update from upstream |
 | ⇅ | `diverged` | Both sides changed | Will merge from upstream |
 | ⨀ | `pinned` | Both changed, fork wins | Protected, keeping fork: review, see below |
 | + | `local` | Only in fork, never in upstream | No action needed |
 
 ### Protected but behind upstream
 
-A pinned or ignored file wins whole-file: when upstream also changed it since the last sync,
+A pinned or ignored file wins whole-file: when upstream also changed it since the last upgrade,
 upstream's hunks are dropped, not merged. That is easy to miss (a pinned stylesheet quietly
-missing new upstream utilities that synced components rely on), so both commands call it out:
+missing new upstream utilities that merged components rely on), so both commands call it out:
 
 - `analyze` lists them in a `⚠ protected but behind upstream` section (pinned files as ⨀,
-  ignored as ⨂) with the number of lines upstream changed; `--list`/`--json` include them in
-  `--scope all` and `--scope protected` (`--json` adds `upstreamChanged` and `upstreamChangedLines`).
-- `sync` prints the same list at the end of its summary, right when the drop happens.
+  ignored as ⨂) with the number of lines upstream changed, together with the ignored files only
+  upstream changed (tagged `new` or `deleted`, see below). New files come first, then the most
+  changed; generated output the fork regenerates itself (`sdk/gen`, `*.gen.*` files) is left out.
+  `--list`/`--json` include them in `--scope all` and `--scope protected` (`--json` adds
+  `upstreamChanged` and `upstreamChangedLines`).
+- `upgrade` prints the same list at the end of its summary, right when the drop happens.
 
 ```
 ⚠ 3 protected files kept the fork version, dropping upstream changes:
   ⨀ frontend/src/styling/tailwind.css · 21 lines changed upstream
   ⨂ shared/config/default.ts · 4 lines changed upstream
   ⨂ shared/config/staging.ts · 2 lines changed upstream
-  pinned/ignored files where upstream also changed since the last sync; the fork side wins on conflict, so review what upstream changed and adopt what you need.
+  pinned/ignored files where upstream also changed since the last upgrade; the fork side wins on conflict, so review what upstream changed and adopt what you need.
 ```
 
-The [review page](#review-page) shows what upstream changed in each of them since the last sync.
-The check is relative to the last sync point: a drop that happened in an earlier sync only shows
-up as plain `ahead` afterwards. For that case the `↑ protected in fork` section annotates pinned
-files with `· N upstream lines absent` (lines upstream has that the fork lacks, compared at the
-tips, `--json`: `upstreamLinesAbsent`). That is upstream content the fork never received,
+The [review page](#review-page) shows what upstream changed in each of them since the last upgrade.
+The check is relative to the last upgrade: a drop that happened in an earlier upgrade only shows
+up as plain `ahead` afterwards. For that case the `↑ protected in fork` section counts the
+`upstream lines absent` from each pinned file (lines upstream has that the fork lacks, compared at
+the tips, `--json`: `upstreamLinesAbsent`). That is upstream content the fork never received,
 deliberately or not: the review page shows the difference, so you can decide. Ignored files are
 not annotated.
 
-To pull upstream into every pinned file at once, run `sync --unpinned`: pins are lifted for that
+To pull upstream into every pinned file at once, run `upgrade --unpinned`: pins are lifted for that
 run (managed files stay pinned) and the merge uses the full upstream history, so changes earlier
-syncs dropped come back too. Review the staged merge in your editor and keep what you want;
+upgrades dropped come back too. Review the staged merge in your editor and keep what you want;
 `analyze --unpinned` previews it.
 
-### Upstream changes that never sync
+### Upstream changes that never merge
 
-Two more kinds of upstream change never reach the fork on their own. `analyze` prints both after
-its summary, and `sync` after its merge summary:
+Two more kinds of upstream change never reach the fork on their own. `analyze` lists the first in
+`protected but behind upstream` and prints the second after its file sections; `upgrade` prints both
+after its merge summary:
 
 - **Ignored paths changed upstream.** Upstream changed, added or deleted a file under an `ignored`
   entry (app-owned module folders included) and the fork left it untouched. No conflict marks it,
-  so this is where new config keys and version bumps under `shared/config` show up. Each `ignored`
-  entry gets one line with a file count, and the [review page](#review-page) shows the diffs. Files
+  so this is where new config keys and version bumps under `shared/config` show up. In `upgrade`
+  each `ignored` entry gets one line with a file count, and the [review page](#review-page) shows
+  the diffs. Files
   both sides changed stay in the section above, and generated output the fork regenerates itself
   (`sdk/gen`, `*.gen.*` files) is left out. `--list`/`--json` include these
   files in `--scope all` and `--scope protected` (`--json`: `upstreamOnly`).
-- **Upstream sync config changes.** `cella/cella.config.ts` never syncs, so entries upstream adds to
-  its own `overrides.pinned` or `overrides.ignored`, and keys it adds to `settings.packageJsonSync`
+- **Upstream CLI config changes.** `cella/cella.config.ts` never merges, so entries upstream adds to
+  its own `overrides.pinned` or `overrides.ignored`, and keys it adds to `settings.packageJsonKeys`
   (the template your config started from), never arrive. The report names each entry upstream added
   that your config lacks (`+`) and each entry upstream dropped that your config still has (`−`). It
   reads upstream's config without running it and never edits yours. `--json` puts the lists on the
@@ -277,76 +332,79 @@ its summary, and `sync` after its merge summary:
 ```
 ⚠ ignored paths changed upstream · 1 file under 1 entry
   ⨂ frontend/src/modules/marketing · 1 file
-  the fork left these untouched and ignored paths never sync: review and adopt what you need.
+  the fork left these untouched and ignored paths never merge: review and adopt what you need.
 
-⚠ upstream changed its sync config · 2 entries to review
+⚠ upstream changed its CLI config · 2 entries to review
   + pinned: backend/src/bundle-config.ts
-  + packageJsonSync: exports
-  cella/cella.config.ts never syncs: add or drop these by hand where they fit your app.
+  + packageJsonKeys: exports
+  cella/cella.config.ts never merges: add or drop these by hand where they fit your app.
 ```
 
-`analyze` only reports these. `sync` checks the sync config before a new merge and stops when it
+`analyze` only reports these. `upgrade` checks the CLI config before a new merge and stops when it
 finds entries: the merge runs on your config, so with a list that is behind, a path upstream now
-ignores or pins would arrive as an ordinary synced file (upstream renamed an ignored folder, your
+ignores or pins would arrive as an ordinary merged file (upstream renamed an ignored folder, your
 list still names the old one). Nothing has changed at that point. Add or drop the entries that fit
 your app in `cella/cella.config.ts`, commit and rerun, or pass `--keep-config` to merge with your
 config as it stands; the report then follows the merge summary as before. The rerun that commits an
 already staged merge never stops for this.
 
 ```bash
-pnpm cella sync --keep-config   # merge although upstream changed its sync config
+pnpm cella upgrade --keep-config   # merge although upstream changed its CLI config
 ```
 
 ### Review page
 
 The terminal lists files; the review page shows their diffs, side by side and highlighted, on one
-page in your browser under the same section titles. `analyze` and `sync` write it whenever a list
-has files, and print its path last:
+page in your browser under the same section titles. `analyze` and `upgrade` write it whenever a list
+has files, and list it first under [`next steps`](#analyze-output):
 
 ```
-⧈ review page with 3 diffs, opened in the browser:
-  /Users/you/app/.git/cella-diff/sync-review.html
+  1 review   file:///Users/you/app/.git/cella-diff/upgrade-review.html
+             3 diffs of upstream changes that did not arrive · opened in the browser
 ```
 
-| Section | `analyze` | `sync` | The diff shows |
+| Section | `analyze` | `upgrade` | The diff shows |
 | --- | --- | --- | --- |
-| protected but behind upstream (sync: protected files kept the fork version) | ✓ | ✓ | what upstream changed since the last sync |
-| ignored paths changed upstream | ✓ | ✓ | what upstream changed since the last sync |
-| pinned files that match the previous upstream | ✓ | ✓ | what upstream changed since the last sync |
+| protected but behind upstream (upgrade: protected files kept the fork version) | ✓ | ✓ | what upstream changed since the last upgrade |
+| ignored paths changed upstream (analyze: under protected but behind upstream) | ✓ | ✓ | what upstream changed since the last upgrade |
+| pinned files that match the previous upstream | ✓ | ✓ | what upstream changed since the last upgrade |
 | protected in fork, upstream lines absent | ✓ | | the fork against upstream, both as they are now |
-| drifted from upstream | ✓ | | what the fork changed since the last sync |
+| drifted from upstream | ✓ | | what the fork changed since the last upgrade |
 
-`sync` opens the page in your browser when it runs in a terminal: the files on it are upstream
-changes the merge did not bring in, and the committed sync branch is where you adopt them.
-`analyze` only prints the path, since you run it often and pinned files keep their absent lines.
+`upgrade` opens the page in your browser when it runs in a terminal: the files on it are upstream
+changes the merge did not bring in, and the committed upgrade branch is where you adopt them.
+`analyze` only lists the page, since you run it often and pinned files keep their absent lines.
 The page lives in the git dir, so it never shows up in `git status`, and each run overwrites it. It
-holds 50 diffs at most; the rest, and files without a text diff, are listed by path.
+renders at most 50 diffs and 15,000 diff lines, and a single diff over 2,000 lines is listed
+instead (a rendered line costs about 0.6 KB of page). Sections take turns, one file each, so every
+section gets diffs before one fills the page. The rest, and files without a text diff, are listed
+by path.
 
-## Package.json sync
+## Package.json merge
 
-`packageJsonSync` controls which package.json sections sync from upstream:
+`packageJsonKeys` controls which package.json sections merge from upstream:
 
 ```typescript
-packageJsonSync: ['dependencies', 'devDependencies', 'scripts']
+packageJsonKeys: ['dependencies', 'devDependencies', 'scripts']
 ```
 
 **Supported keys:** `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`, `scripts`, `engines`, `packageManager`, `overrides`, `exports`, `pnpm`
 
 Each section merges three-way against the merge-base package.json (upstream as of your last
-sync). An entry your fork never touched follows upstream: it is **added**, **updated** (a rewritten
+upgrade). An entry your fork never touched follows upstream: it is **added**, **updated** (a rewritten
 script, a changed range) or **removed** when upstream dropped it. An entry your fork added or
 changed stays as it is; only a strictly higher upstream version still bumps it, and never for
 `scripts`. An entry your fork removed is not re-added. A dependency or script upstream dropped
 stays while your own code still uses it: files that differ from upstream and scripts your fork
 added or changed are searched for an import of the package, a run of its CLI, or a package manager
-command that runs the script. The sync lists every change and warns about each entry it kept this
+command that runs the script. The upgrade lists every change and warns about each entry it kept this
 way, so you can remove it once your code no longer needs it. `exports` are add-only: an entry your fork
 already defines is never rewritten, and `exports` only merges when both sides are subpath maps
-(`{ ".": …, "./config": … }`). A workspace upstream added since your last sync arrives with its
+(`{ ".": …, "./config": … }`). A workspace upstream added since your last upgrade arrives with its
 package.json copied verbatim. A merged section is sorted alphabetically, except `scripts`: they
 keep upstream's order, and a script only your fork has stays after the one it follows.
 
-`type` always syncs, whatever `packageJsonSync` lists: it follows upstream where your fork kept the
+`type` always merges, whatever `packageJsonKeys` lists: it follows upstream where your fork kept the
 previous value, and a package.json without `type` gets upstream's. Set it yourself (for example
 `"commonjs"`) to keep your own.
 

package/dist/config.d.ts

@@ -3,11 +3,11 @@
  * schema, and the internal types the services share.
  */
 
-declare const PACKAGE_JSON_SYNC_KEYS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies", "scripts", "engines", "packageManager", "overrides", "exports", "pnpm"];
-/** Valid package.json keys that can be synced */
-type PackageJsonSyncKey = (typeof PACKAGE_JSON_SYNC_KEYS)[number];
+declare const PACKAGE_JSON_KEYS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies", "scripts", "engines", "packageManager", "overrides", "exports", "pnpm"];
+/** Valid package.json keys that can merge from upstream */
+type PackageJsonKey = (typeof PACKAGE_JSON_KEYS)[number];
 /**
- * Sync settings: all configurable options for the sync CLI.
+ * Settings: all configurable options for the cella CLI.
  * Hover over each property for documentation.
  */
 interface SyncSettings {
@@ -20,21 +20,25 @@ interface SyncSettings {
     upstreamBranch?: string;
     /**
      * How to track upstream cella. Defaults to 'release'.
-     * - 'release' (default): sync to a published cella release tag (`0.18.1`, with or without `v`). Stable and
+     * - 'release' (default): upgrade to a published cella release tag (`0.18.1`, with or without `v`). Stable and
      *   reviewable: each bump maps to a changelog. Uses the latest release.
      * - 'branch': follow the bleeding-edge tip of `upstreamBranch`. For cella
      *   maintainers and forks doing active development on top of unreleased changes.
      */
     upstreamTrack?: 'release' | 'branch';
     /**
-     * Trunk branch that `pnpm cella sync` cuts the temporary branch from and that you open the
+     * Trunk branch that `pnpm cella upgrade` cuts the temporary branch from and that you open the
      * squash-merge PR into. Defaults to 'main'. Cutting fresh from trunk each cycle keeps every
      * PR limited to that cycle's upstream delta (no accumulation) and `main` linear.
      */
     releaseBase?: string;
-    /** Which package.json keys to sync (default: ['dependencies', 'devDependencies']). `type` always syncs. */
-    packageJsonSync?: PackageJsonSyncKey[];
-    /** Automatic package.json sync after the sync service completes (default: true). Set to false to turn it off. */
+    /** Which package.json keys merge from upstream (default: ['dependencies', 'devDependencies']). `type` always merges. */
+    packageJsonKeys?: PackageJsonKey[];
+    /** Merge the `packageJsonKeys` of every package.json after the upgrade merge (default: true). */
+    mergePackageJson?: boolean;
+    /** @deprecated Renamed to `packageJsonKeys`. */
+    packageJsonSync?: PackageJsonKey[];
+    /** @deprecated Renamed to `mergePackageJson`. */
     syncWithPackages?: boolean;
     /**
      * How to link files in CLI output.
@@ -48,7 +52,7 @@ interface SyncSettings {
  *
  * Cella is the upstream/source-of-truth. For each fork it can:
  * - pull contributions FROM the fork's `pullBranch` (contributions service)
- * - run the normal temporary-branch sync flow inside the fork (forks service)
+ * - run the normal temporary-branch upgrade flow inside the fork (forks service)
  */
 interface ForkConfig {
     /** Display name for the fork (also used as the contrib/<name> branch slug) */
@@ -102,4 +106,4 @@ interface CellaCliConfig {
  */
 declare function defineConfig(config: CellaCliConfig): CellaCliConfig;
 
-export { type CellaCliConfig, type PackageJsonSyncKey, defineConfig };
+export { type CellaCliConfig, type PackageJsonKey, defineConfig };

package/dist/config.js

@@ -1,6 +1,6 @@
 // src/config/types.ts
 import { z } from "zod";
-var PACKAGE_JSON_SYNC_KEYS = [
+var PACKAGE_JSON_KEYS = [
   "dependencies",
   "devDependencies",
   "peerDependencies",
@@ -21,7 +21,9 @@ var cellaConfigSchema = z.object({
     upstreamBranch: z.string().min(1).optional(),
     upstreamTrack: z.enum(["release", "branch"]).optional(),
     releaseBase: z.string().min(1).optional(),
-    packageJsonSync: z.array(z.enum(PACKAGE_JSON_SYNC_KEYS)).optional(),
+    packageJsonKeys: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),
+    mergePackageJson: z.boolean().optional(),
+    packageJsonSync: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),
     syncWithPackages: z.boolean().optional(),
     fileLinkMode: z.enum(["commit", "file"]).optional()
   }).strict(),