@cellajs/cli 0.5.0 → 0.6.0

package/dist/index.js

@@ -57,7 +57,7 @@ import { z as z2 } from "zod";
 
 // src/config/types.ts
 import { z } from "zod";
-var PACKAGE_JSON_SYNC_KEYS = [
+var PACKAGE_JSON_KEYS = [
   "dependencies",
   "devDependencies",
   "peerDependencies",
@@ -75,7 +75,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(),
@@ -156,13 +158,18 @@ function resolveAppModuleFolders(repoPath) {
 // src/utils/config.ts
 var DEFAULT_UPSTREAM_REMOTE = "cella-upstream";
 var DEFAULT_BRANCH = "main";
-var DEFAULT_SYNC_PREFIX = "cella/sync";
-var DEFAULT_PACKAGE_JSON_SYNC = ["dependencies", "devDependencies"];
+var UPGRADE_BRANCH_PREFIX = "cella/upgrade";
+var TEMPORARY_BRANCH_PREFIXES = [UPGRADE_BRANCH_PREFIX, "cella/sync"];
+var DEFAULT_PACKAGE_JSON_KEYS = ["dependencies", "devDependencies"];
+var RENAMED_SETTINGS = { packageJsonSync: "packageJsonKeys", syncWithPackages: "mergePackageJson" };
+function renamedSettingWarnings(config) {
+  return Object.entries(RENAMED_SETTINGS).filter(([old]) => old in config.settings).map(([old, current]) => `settings.${old} is renamed to ${current}: rename it in ${CONFIG_FILE}`);
+}
 function isUpstreamRepo(repoPath) {
   return JSON.parse(readFileSync(join2(repoPath, "package.json"), "utf8")).name === "cella";
 }
 function isTemporarySyncBranch(branch) {
-  return branch.startsWith(`${DEFAULT_SYNC_PREFIX}/`);
+  return TEMPORARY_BRANCH_PREFIXES.some((prefix) => branch.startsWith(`${prefix}/`));
 }
 function resolveReleaseBase(settings) {
   return settings.releaseBase ?? DEFAULT_BRANCH;
@@ -171,7 +178,7 @@ function buildTemporarySyncBranch() {
   const now = /* @__PURE__ */ new Date();
   const pad2 = (n) => String(n).padStart(2, "0");
   const stamp = `${now.getFullYear()}${pad2(now.getMonth() + 1)}${pad2(now.getDate())}-${pad2(now.getHours())}${pad2(now.getMinutes())}`;
-  return `${DEFAULT_SYNC_PREFIX}/${stamp}`;
+  return `${UPGRADE_BRANCH_PREFIX}/${stamp}`;
 }
 function resolveUpstream(settings) {
   const track = settings.upstreamTrack ?? "release";
@@ -201,6 +208,8 @@ async function loadConfig(forkPath) {
 ${z2.prettifyError(result.error)}`);
   }
   const config = result.data;
+  config.settings.packageJsonKeys ??= config.settings.packageJsonSync;
+  config.settings.mergePackageJson ??= config.settings.syncWithPackages;
   const appModuleFolders = resolveAppModuleFolders(realForkPath);
   if (appModuleFolders.length > 0) {
     const existing = config.overrides?.ignored ?? [];
@@ -219,10 +228,10 @@ import process5 from "process";
 // package.json
 var package_default = {
   name: "@cellajs/cli",
-  version: "0.5.0",
+  version: "0.6.0",
   private: false,
   license: "MIT",
-  description: "CLI for managing your monorepo and syncing with upstream Cella.",
+  description: "CLI for managing your monorepo and upgrading it with upstream Cella.",
   repository: {
     type: "git",
     url: "https://github.com/cellajs/cella-cli"
@@ -746,16 +755,25 @@ async function cleanupEmptyParentDirs(cwd, relativePath) {
   } catch {
   }
 }
+var LAST_UPGRADE_REF = "refs/cella/last-upgrade";
+var LEGACY_LAST_UPGRADE_REF = "refs/cella/last-sync";
 async function storeLastSyncRef(cwd, upstreamHash) {
-  await git(["update-ref", "refs/cella/last-sync", upstreamHash], cwd);
+  await git(["update-ref", LAST_UPGRADE_REF, upstreamHash], cwd);
   const head = await revParse(cwd, "HEAD");
-  if (head) await git(["update-ref", "refs/cella/last-sync-head", head], cwd);
+  if (head) await git(["update-ref", `${LAST_UPGRADE_REF}-head`, head], cwd);
 }
 async function stagePath(cwd, path) {
   await git(["add", "--", path], cwd, { ignoreErrors: true });
 }
+async function readStoredSyncRefs(cwd) {
+  for (const name of [LAST_UPGRADE_REF, LEGACY_LAST_UPGRADE_REF]) {
+    const ref = await revParse(cwd, name);
+    if (ref) return { ref, head: await revParse(cwd, `${name}-head`) };
+  }
+  return null;
+}
 async function getStoredSyncRef(cwd) {
-  return revParse(cwd, "refs/cella/last-sync");
+  return (await readStoredSyncRefs(cwd))?.ref ?? null;
 }
 async function readManifestAtRef(cwd, ref) {
   const raw = await git(["show", `${ref}:${MANIFEST_FILE}`], cwd, { ignoreErrors: true });
@@ -804,11 +822,11 @@ async function unshallowRepository(cwd) {
 ${error.message}` : "";
     throw new Error(
       `this is a shallow clone and its full history could not be restored automatically.
-Sync needs the complete history to find the common ancestor with upstream. Restore it with:
+An upgrade needs the complete history to find the common ancestor with upstream. Restore it with:
 
   git fetch --unshallow
 
-then re-run sync.${detail}`
+then re-run the upgrade.${detail}`
     );
   }
 }
@@ -834,20 +852,20 @@ async function ensureSyncBase(cwd, headRef, upstreamRef) {
   }
   if (!baseSha) {
     throw new Error(
-      `no common ancestor between the fork and '${upstreamRef}', and no sync base could be determined.
+      `no common ancestor between the fork and '${upstreamRef}', and no upgrade base could be determined.
 
 This fork has unrelated history with upstream (typical for a create-cella scaffold, or after
 upstream squashed its history) and no recorded base commit exists after fetching
-upstream. Seed it manually with the upstream commit the fork was created from, then re-run sync:
+upstream. Seed it manually with the upstream commit the fork was created from, then re-run the upgrade:
 
-  git update-ref refs/cella/last-sync <upstream-sha>
+  git update-ref ${LAST_UPGRADE_REF} <upstream-sha>
 `
     );
   }
   const root = await getRootCommit(cwd, headRef);
-  if (!root) throw new Error("could not determine the fork's root commit to bootstrap sync ancestry");
+  if (!root) throw new Error("could not determine the fork's root commit to bootstrap upgrade ancestry");
   await git(["replace", "-f", "--graft", root, baseSha], cwd);
-  await git(["update-ref", "refs/cella/last-sync", baseSha], cwd);
+  await git(["update-ref", LAST_UPGRADE_REF, baseSha], cwd);
 }
 async function isAncestor(cwd, ancestor, descendant) {
   try {
@@ -858,14 +876,13 @@ async function isAncestor(cwd, ancestor, descendant) {
   }
 }
 async function getLegacySyncRef(cwd, headRef) {
-  const storedRef = await getStoredSyncRef(cwd);
-  if (!storedRef) return null;
-  const storedHead = await revParse(cwd, "refs/cella/last-sync-head");
-  if (storedHead) {
+  const stored = await readStoredSyncRefs(cwd);
+  if (!stored) return null;
+  if (stored.head) {
     const currentHead = await revParse(cwd, headRef);
-    if (currentHead && currentHead === storedHead) return null;
+    if (currentHead && currentHead === stored.head) return null;
   }
-  return storedRef;
+  return stored.ref;
 }
 async function getEffectiveMergeBase(cwd, headRef, upstreamRef) {
   const gitBase = await getMergeBase(cwd, headRef, upstreamRef);
@@ -1044,7 +1061,7 @@ ${colors_default.dim(forkPath)}`;
 }
 function formatUpstreamStep(upstream) {
   const { label, sha, baseSha, pinned, commitCount, commits, githubUrl } = upstream;
-  const since = commitCount === 0 ? "no new commits since the last sync" : `${plural(commitCount, "new commit")} since the last sync at ${baseSha}`;
+  const since = commitCount === 0 ? "no new commits since the last upgrade" : `${plural(commitCount, "new commit")} since the last upgrade at ${baseSha}`;
   return [
     `${label} @ ${sha}${colors_default.dim(`${pinned ? " \xB7 --ref" : ""} \xB7 ${since}`)}`,
     ...formatUpstreamCommits(commitCount, commits, githubUrl)
@@ -1111,7 +1128,7 @@ function formatMergeInProgressDetail(conflictCount, autoMergedFiles, linkOptions
   return lines.join("\n");
 }
 var statusConfig = {
-  behind: { icon: colors_default.cyan("\u2193"), label: "behind", color: colors_default.cyan, description: "upstream changed, will sync" },
+  behind: { icon: colors_default.cyan("\u2193"), label: "behind", color: colors_default.cyan, description: "upstream changed, will update" },
   diverged: { icon: colors_default.magenta("\u21C5"), label: "diverged", color: colors_default.magenta, description: "both changed, will merge" },
   drifted: { icon: colors_default.yellow("!"), label: "drifted", color: colors_default.yellow, description: "fork changed (at risk)" },
   ahead: { icon: colors_default.blue("\u2191"), label: "ahead", color: colors_default.blue, description: "fork changed (protected)" },
@@ -1162,7 +1179,7 @@ function findProtectedBehindUpstream(result) {
   const ignoredOnly = new Set((result.ignoredUpstreamChanges ?? []).flatMap((group) => group.paths));
   return [...findProtectedBehind(result.files), ...result.files.filter((file) => ignoredOnly.has(file.path))];
 }
-var PROTECTED_BEHIND_HINT = "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.";
+var PROTECTED_BEHIND_HINT = "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.";
 function protectionIcon(file) {
   return file.isIgnored ? statusConfig.ignored.icon : statusConfig.pinned.icon;
 }
@@ -1178,13 +1195,13 @@ function printSyncComplete(result, options = {}) {
   const counts = `${plural(updated, "file")} updated, ${merged} auto-merged, ${plural(conflicts, "conflict")}`;
   console.info();
   if (options.stagedBranch) {
-    console.info(`${checkMark} sync merge staged on '${options.stagedBranch}'`);
+    console.info(`${checkMark} upgrade merge staged on '${options.stagedBranch}'`);
     console.info(colors_default.dim(`  ${counts}. committing next...`));
   } else if (conflicts > 0) {
-    console.info(`${warningMark} sync merge staged with conflicts`);
+    console.info(`${warningMark} upgrade merge staged with conflicts`);
     console.info(colors_default.dim(`  ${counts}`));
   } else {
-    console.info(`${checkMark} sync complete`);
+    console.info(`${checkMark} upgrade merge complete`);
     console.info(colors_default.dim(`  ${counts}`));
   }
   printProtectedConflicts(result);
@@ -1224,31 +1241,33 @@ function printIgnoredUpstreamChanges(result) {
     if (group.deleted > 0) counts.push(`${group.deleted} deleted`);
     console.info(`  ${statusConfig.ignored.icon} ${group.entry} ${colors_default.dim(`\xB7 ${counts.join(", ")}`)}`);
   }
-  console.info(colors_default.dim("  the fork left these untouched and ignored paths never sync: review and adopt what you need."));
+  console.info(
+    colors_default.dim("  the fork left these untouched and ignored paths never merge: review and adopt what you need.")
+  );
 }
 function printUpstreamOverrideChanges(result) {
   const report = result.upstreamOverrides;
   if (!report) return;
   console.info();
   if (report.kind === "unreadable") {
-    const side = report.side === "base" ? "the last sync point" : "the incoming ref";
+    const side = report.side === "base" ? "the last upgrade" : "the incoming ref";
     console.info(
-      colors_default.dim(`upstream sync config not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
+      colors_default.dim(`upstream CLI config not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
     );
     return;
   }
   const lines = [];
-  for (const list of ["pinned", "ignored", "packageJsonSync"]) {
+  for (const list of ["pinned", "ignored", "packageJsonKeys"]) {
     for (const entry of report[list].added) lines.push(`  ${colors_default.green("+")} ${list}: ${entry}`);
     for (const entry of report[list].removed) {
       lines.push(`  ${colors_default.red("\u2212")} ${list}: ${entry}${colors_default.dim(" \xB7 dropped upstream, still in your config")}`);
     }
   }
   console.info(
-    `${warningMark} ${colors_default.yellow(`upstream changed its sync config \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
+    `${warningMark} ${colors_default.yellow(`upstream changed its CLI config \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
   );
   for (const line of lines) console.info(line);
-  console.info(colors_default.dim(`  ${CONFIG_FILE} never syncs: add or drop these by hand where they fit your app.`));
+  console.info(colors_default.dim(`  ${CONFIG_FILE} never merges: add or drop these by hand where they fit your app.`));
 }
 function findMaskingPins(files) {
   return files.filter(
@@ -1327,7 +1346,8 @@ function parseAlignment(id, source, fileNames) {
     id,
     title: title || id,
     summary,
-    syncBreaking: meta.get("syncBreaking") === "true",
+    // `syncBreaking` is the field's name in alignments up to cella 0.27
+    breaking: (meta.get("breaking") ?? meta.get("syncBreaking")) === "true",
     clientCacheBump: meta.get("clientCacheBump") === "true",
     caughtBy,
     generate: meta.get("generate") === "true",
@@ -1532,7 +1552,7 @@ var forkOption = ["--fork <name>", "pre-select a fork by name (skips the fork se
 var serviceDefinitions = [
   {
     name: "analyze",
-    description: "dry run to see what would change on sync",
+    description: "dry run to see what would change on upgrade",
     options: [
       ["--list", "non-interactive output for tooling (one file per line)"],
       jsonOption,
@@ -1545,12 +1565,13 @@ var serviceDefinitions = [
     includeInMenu: (context) => !context.isUpstreamRepo
   },
   {
-    name: "sync",
-    description: "merge upstream changes onto a fresh branch, sync package.json and open a squash-merge PR",
+    name: "upgrade",
+    description: "merge upstream changes onto a fresh branch, merge package.json and open a squash-merge PR",
+    aliases: ["sync"],
     options: [
       trackOption,
       refOption,
-      ["--keep-config", "merge with your sync config as it stands when upstream changed its own"],
+      ["--keep-config", "merge with your CLI config as it stands when upstream changed its own"],
       unpinnedOption
     ],
     includeInMenu: (context) => !context.isUpstreamRepo
@@ -1579,10 +1600,10 @@ var serviceDefinitions = [
   },
   {
     name: "forks",
-    description: "run normal sync inside local fork repositories",
+    description: "run the upgrade inside local fork repositories",
     options: [
       forkOption,
-      ["--keep-config", "merge with the fork's sync config as it stands when upstream changed its own"]
+      ["--keep-config", "merge with the fork's CLI config as it stands when upstream changed its own"]
     ],
     includeInMenu: (context) => context.hasForks
   },
@@ -1621,17 +1642,21 @@ function buildServiceChoices(context) {
   ];
 }
 function addServiceCommand(program, definition, setSelection) {
-  const command = program.command(definition.name).description(definition.description);
-  for (const option of definition.options ?? []) command.option(...option);
-  if (definition.operands) command.argument(...definition.operands);
-  command.action((...args) => {
-    const operands = definition.operands ? args[0] : [];
-    const opts = definition.operands ? args[1] : args[0];
-    setSelection({
-      service: definition.name,
-      options: readOptions(opts, operands)
+  for (const name of [definition.name, ...definition.aliases ?? []]) {
+    const renamedFrom = name === definition.name ? void 0 : name;
+    const command = program.command(name, { hidden: !!renamedFrom }).description(definition.description);
+    for (const option of definition.options ?? []) command.option(...option);
+    if (definition.operands) command.argument(...definition.operands);
+    command.action((...args) => {
+      const operands = definition.operands ? args[0] : [];
+      const opts = definition.operands ? args[1] : args[0];
+      setSelection({
+        service: definition.name,
+        renamedFrom,
+        options: readOptions(opts, operands)
+      });
     });
-  });
+  }
 }
 function buildProgram(setSelection) {
   const program = new Command("cella").version(VERSION, "-v, --version", "output the current version").usage("[service] [options]").helpOption("-h, --help", "display help for a command").showHelpAfterError().addHelpText(
@@ -1641,8 +1666,8 @@ function buildProgram(setSelection) {
       "Examples:",
       "  $ cella analyze",
       "  $ cella analyze --json --scope risk",
-      "  $ cella sync --track branch",
-      "  $ cella sync --ref 4f7d87c",
+      "  $ cella upgrade --track branch",
+      "  $ cella upgrade --ref 4f7d87c",
       "  $ cella align --run 20261001T2116-tailwind-class-conventions -- rewrite frontend/src",
       "  $ cella align --mark 20261002T0614-config-switch",
       "  $ cella audit --list",
@@ -1689,7 +1714,13 @@ async function parseCli(userConfig, forkPath) {
   if (selection.options.json || selection.options.md || machineList) setJsonMode(true);
   printHeader();
   const { branchRef } = resolveUpstream(userConfig.settings);
-  const warnings = await validateOverrides(userConfig, forkPath, branchRef);
+  const warnings = [
+    ...renamedSettingWarnings(userConfig),
+    ...await validateOverrides(userConfig, forkPath, branchRef)
+  ];
+  if (selection.renamedFrom) {
+    warnings.unshift(`\`cella ${selection.renamedFrom}\` is renamed to \`cella ${selection.service}\``);
+  }
   for (const warning of warnings) console.info(`${warningMark} ${warning}`);
   if (warnings.length > 0) console.info();
   if (!selection.service) {
@@ -1778,7 +1809,7 @@ function cliVersionMismatch(running, range) {
   const current = parseComparableVersion(running);
   if (!required || !current || compareVersions(current, required) >= 0) return null;
   return [
-    `upstream needs ${CLI_PACKAGE} ${range}, this is ${running}: an older CLI misses fixes to the sync itself.`,
+    `upstream needs ${CLI_PACKAGE} ${range}, this is ${running}: an older CLI misses fixes to the upgrade itself.`,
     `  update it, commit, then rerun: pnpm add -D -w '${CLI_PACKAGE}@${range}'`
   ].join("\n");
 }
@@ -1832,12 +1863,13 @@ function readStringEntries(node) {
   }
   return entries;
 }
-function readPackageJsonSync(config, sourceFile) {
+function readPackageJsonKeys(config, sourceFile) {
   const settings = readProperty(config, "settings", sourceFile);
-  if (settings === void 0) return [...DEFAULT_PACKAGE_JSON_SYNC];
+  if (settings === void 0) return [...DEFAULT_PACKAGE_JSON_KEYS];
   if (!settings || !Node.isObjectLiteralExpression(settings)) return null;
-  const keys = readProperty(settings, "packageJsonSync", sourceFile);
-  if (keys === void 0) return [...DEFAULT_PACKAGE_JSON_SYNC];
+  const current = readProperty(settings, "packageJsonKeys", sourceFile);
+  const keys = current === void 0 ? readProperty(settings, "packageJsonSync", sourceFile) : current;
+  if (keys === void 0) return [...DEFAULT_PACKAGE_JSON_KEYS];
   return keys ? readStringEntries(keys) : null;
 }
 function parseOverrideLists(source) {
@@ -1849,7 +1881,7 @@ function parseOverrideLists(source) {
     const lists = {
       pinned: [],
       ignored: [],
-      packageJsonSync: readPackageJsonSync(config, sourceFile)
+      packageJsonKeys: readPackageJsonKeys(config, sourceFile)
     };
     const overrides = readProperty(config, "overrides", sourceFile);
     if (overrides === void 0) return lists;
@@ -1877,14 +1909,14 @@ function diffOverrideLists(base, incoming, fork) {
     };
   };
   const diffKeys = () => {
-    const [baseKeys, incomingKeys, forkKeys] = [base.packageJsonSync, incoming.packageJsonSync, fork.packageJsonSync];
+    const [baseKeys, incomingKeys, forkKeys] = [base.packageJsonKeys, incoming.packageJsonKeys, fork.packageJsonKeys];
     if (!baseKeys || !incomingKeys || !forkKeys) return { added: [], removed: [] };
     return {
       added: [...new Set(incomingKeys)].filter((key) => !baseKeys.includes(key) && !forkKeys.includes(key)),
       removed: [...new Set(baseKeys)].filter((key) => !incomingKeys.includes(key) && forkKeys.includes(key))
     };
   };
-  return { pinned: diff("pinned"), ignored: diff("ignored"), packageJsonSync: diffKeys() };
+  return { pinned: diff("pinned"), ignored: diff("ignored"), packageJsonKeys: diffKeys() };
 }
 async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, forkConfig) {
   const [baseSource, incomingSource] = await Promise.all(
@@ -1898,7 +1930,7 @@ async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, for
   const fork = {
     pinned: forkConfig.overrides?.pinned ?? [],
     ignored: forkConfig.overrides?.ignored ?? [],
-    packageJsonSync: forkConfig.settings.packageJsonSync ?? DEFAULT_PACKAGE_JSON_SYNC
+    packageJsonKeys: forkConfig.settings.packageJsonKeys ?? DEFAULT_PACKAGE_JSON_KEYS
   };
   const changes = diffOverrideLists(base, incoming, fork);
   const count3 = Object.values(changes).reduce((n, list) => n + list.added.length + list.removed.length, 0);
@@ -2094,7 +2126,7 @@ var UpstreamConfigChangedError = class extends Error {
   constructor(report) {
     super(
       [
-        "upstream changed its sync config and yours does not follow it: stopped before the merge, nothing changed.",
+        "upstream changed its CLI config and yours does not follow it: stopped before the merge, nothing changed.",
         `  add or drop the entries that fit your app in ${CONFIG_FILE}, commit, then rerun.`,
         "  to merge with your config as it stands, rerun with --keep-config."
       ].join("\n")
@@ -2254,7 +2286,7 @@ async function resolvePinnedRef(forkPath, config, remoteName, branchRef, ref) {
   }
   if (!await isPublishedUpstream(forkPath, remoteName, branchRef, resolved.sha)) {
     throw new Error(
-      `--ref '${ref}' (${resolved.sha.slice(0, 7)}) is not on ${branchRef} or in an upstream release. Sync only to commits upstream has published there.`
+      `--ref '${ref}' (${resolved.sha.slice(0, 7)}) is not on ${branchRef} or in an upstream release. Upgrade only to commits upstream has published there.`
     );
   }
   return resolved.release ? { ref: resolved.release.ref, releaseTag: resolved.release.tag } : { ref: resolved.sha };
@@ -2310,9 +2342,9 @@ async function prepareUpstream(config, onProgress, onStep) {
       getShortSha(forkPath, upstreamCommit.hash),
       getShortSha(forkPath, mergeBase)
     ]);
-    const hint2 = config.ref ? "Pick a newer --ref." : releaseTag ? `Nothing to sync until a release past ${syncShort}; to follow the tip instead, run with --track branch.` : `Nothing to sync until '${branchRef}' moves past ${syncShort}.`;
+    const hint2 = config.ref ? "Pick a newer --ref." : releaseTag ? `Nothing to upgrade until a release past ${syncShort}; to follow the tip instead, run with --track branch.` : `Nothing to upgrade until '${branchRef}' moves past ${syncShort}.`;
     throw new BehindSyncPointError(
-      `upstream ${upstreamLabel} (${upstreamShort2}) is behind the last sync point ${syncShort}: the fork already has it, and syncing it would revert the upstream changes after it.
+      `upstream ${upstreamLabel} (${upstreamShort2}) is behind the last upgrade at ${syncShort}: the fork already has it, and merging it would revert the upstream changes after it.
 ${hint2}`
     );
   }
@@ -2422,7 +2454,7 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
       commit: upstreamCommit.hash,
       release: releaseTag ?? null,
       url: upstreamGitHubUrl ? releaseTag ? `${upstreamGitHubUrl}/releases/tag/${releaseTag}` : `${upstreamGitHubUrl}/commit/${upstreamCommit.hash}` : void 0,
-      syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+      upgradedAt: (/* @__PURE__ */ new Date()).toISOString()
     }
   };
   const recordSyncPoint = async () => {
@@ -2441,10 +2473,10 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
   } else if (totalResolved > 0) {
     const label = synced > 0 ? `${synced} files from upstream` : "upstream changes";
     await recordSyncPoint();
-    onStep?.("synced", `${label} (staged, commit to finish)`);
+    onStep?.("upgraded", `${label} (staged, commit to finish)`);
   } else {
     await mergeAbort(forkPath);
-    onStep?.("up to date", "no upstream changes to sync");
+    onStep?.("up to date", "no upstream changes to merge");
   }
   return {
     success: remainingConflicts.length === 0,
@@ -2529,7 +2561,7 @@ var STEP_ROWS_MAX = 5;
 function alignmentTags(alignment) {
   return [
     alignment.codemod ? "codemod" : "manual",
-    alignment.syncBreaking ? "sync-breaking" : "not sync-breaking",
+    alignment.breaking ? "breaking" : "not breaking",
     alignment.caughtBy ? `caught by ${alignment.caughtBy}` : null
   ].filter(Boolean).join(" \xB7 ");
 }
@@ -2538,7 +2570,7 @@ async function alignmentsStep(config, view) {
   const open = view.open.filter((id) => !arriving.includes(id));
   const arrived = (view.arrived ?? []).filter((id) => open.includes(id));
   if (arriving.length === 0 && open.length === 0) return void 0;
-  const line = arriving.length > 0 ? `${plural(arriving.length, "alignment")} ${arriving.length === 1 ? "arrives" : "arrive"} with this sync${open.length > 0 ? colors_default.dim(` \xB7 ${open.length} open`) : ""}` : `${plural(open.length, "alignment")} open${arrived.length > 0 ? colors_default.dim(` \xB7 ${arrived.length} arrived with this sync`) : ""}`;
+  const line = arriving.length > 0 ? `${plural(arriving.length, "alignment")} ${arriving.length === 1 ? "arrives" : "arrive"} with this upgrade${open.length > 0 ? colors_default.dim(` \xB7 ${open.length} open`) : ""}` : `${plural(open.length, "alignment")} open${arrived.length > 0 ? colors_default.dim(` \xB7 ${arrived.length} arrived with this upgrade`) : ""}`;
   const githubUrl = getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0;
   const ids = [...arriving, ...open];
   const details = [];
@@ -2549,7 +2581,7 @@ async function alignmentsStep(config, view) {
     if (!process7.stdout.isTTY) details.push(colors_default.dim(`  id ${id}`));
   }
   if (ids.length > STEP_ROWS_MAX) details.push(colors_default.dim(`+ ${ids.length - STEP_ROWS_MAX} more`));
-  details.push(`${arriving.length > 0 ? colors_default.dim("after the sync: ") : ""}pnpm cella align`);
+  details.push(`${arriving.length > 0 ? colors_default.dim("after the upgrade: ") : ""}pnpm cella align`);
   return { label: "align", line, details };
 }
 async function readForkView(config, ref) {
@@ -2592,7 +2624,7 @@ function grepSummary(alignment) {
 function printAlignment(index, alignment) {
   const tags = [
     alignment.codemod ? "codemod" : "manual",
-    alignment.syncBreaking ? "sync-breaking" : null,
+    alignment.breaking ? "breaking" : null,
     alignment.clientCacheBump ? "cache-bump" : null,
     alignment.caughtBy ? `caught by: ${alignment.caughtBy}` : null,
     alignment.generate ? "generate" : null
@@ -2634,7 +2666,7 @@ async function showAlignment(config, ref, pending, id) {
     alignment,
     pending.includes(id)
   );
-  if (readRef !== ref) console.info(colors_default.dim(`not at the sync point ${ref.slice(0, 7)}: read at ${upstreamBranch}`));
+  if (readRef !== ref) console.info(colors_default.dim(`not at the last upgrade ${ref.slice(0, 7)}: read at ${upstreamBranch}`));
   if (described.url) console.info(colors_default.dim(described.url));
   console.info(source);
   console.info();
@@ -2731,7 +2763,7 @@ async function runAlign(config) {
   const { forkPath } = config;
   const ref = await resolveAlignmentsRef(config);
   if (!ref) {
-    console.info(colors_default.dim("no sync point recorded yet: alignments start with the first `pnpm cella sync`."));
+    console.info(colors_default.dim("no upgrade recorded yet: alignments start with the first `pnpm cella upgrade`."));
     return;
   }
   const pending = await readPending(forkPath);
@@ -2746,7 +2778,7 @@ async function runAlign(config) {
       id: ids[i],
       title: `${ids[i]} (no longer upstream)`,
       summary: "",
-      syncBreaking: false,
+      breaking: false,
       clientCacheBump: false,
       caughtBy: null,
       generate: false,
@@ -3167,30 +3199,30 @@ function reviewSections(result, command) {
   const [base, upstream] = result.upstreamDiffRange?.split("..") ?? [];
   if (!base || !upstream) return [];
   const sinceSync = `${base}..${upstream}`;
-  const sections = command === "sync" ? [
+  const sections = command === "upgrade" ? [
     {
       title: "protected files kept the fork version",
-      hint: "What upstream changed in these files since the last sync. The fork kept its own version, so none of it arrived: adopt what you need.",
+      hint: "What upstream changed in these files since the last upgrade. The fork kept its own version, so none of it arrived: adopt what you need.",
       range: sinceSync,
       paths: result.protectedConflicts ?? []
     },
     {
       title: "ignored paths changed upstream",
-      hint: "What upstream changed under ignored paths since the last sync. The fork left these files untouched, and ignored paths never sync.",
+      hint: "What upstream changed under ignored paths since the last upgrade. The fork left these files untouched, and ignored paths never merge.",
       range: sinceSync,
       paths: (result.ignoredUpstreamChanges ?? []).flatMap((group) => group.paths)
     }
   ] : [
     {
       title: "protected but behind upstream",
-      hint: "What upstream changed in these files since the last sync. They are pinned or ignored, so the sync keeps the fork version and none of it arrives: adopt what you need.",
+      hint: "What upstream changed in these files since the last upgrade. They are pinned or ignored, so the upgrade keeps the fork version and none of it arrives: adopt what you need.",
       range: sinceSync,
       paths: findProtectedBehindUpstream(result).map((file) => file.path)
     }
   ];
   sections.push({
     title: "pinned files that match the previous upstream",
-    hint: "What upstream changed in these files since the last sync. The fork copy still equals the previous upstream, so the pin only drops these changes: unpin to take them.",
+    hint: "What upstream changed in these files since the last upgrade. The fork copy still equals the previous upstream, so the pin only drops these changes: unpin to take them.",
     range: sinceSync,
     paths: findMaskingPins(result.files).map((file) => file.path)
   });
@@ -3198,13 +3230,13 @@ function reviewSections(result, command) {
     sections.push(
       {
         title: "protected in fork, upstream lines absent",
-        hint: "The fork's version against upstream's, both as they are now: added lines are upstream content the fork does not have, dropped by an earlier sync or removed on purpose.",
+        hint: "The fork's version against upstream's, both as they are now: added lines are upstream content the fork does not have, dropped by an earlier upgrade or removed on purpose.",
         range: `HEAD..${upstream}`,
         paths: filesWithStatus(result.files, "ahead").filter((file) => (file.upstreamLinesAbsent ?? 0) > 0).map((file) => file.path)
       },
       {
         title: "drifted from upstream",
-        hint: "What the fork changed in these files since the last sync. They are not pinned or ignored, so upstream changes still merge into them.",
+        hint: "What the fork changed in these files since the last upgrade. They are not pinned or ignored, so upstream changes still merge into them.",
         range: `${base}..HEAD`,
         paths: filesWithStatus(result.files, "drifted").map((file) => file.path)
       }
@@ -3253,7 +3285,7 @@ async function writeReviewPage(forkPath, sections, meta, limits = PAGE_LIMITS) {
   const shown = pageSections.filter((section) => section.files.length > 0 || section.omitted.length > 0);
   const page = await writeDiffPage(
     shown,
-    { title: `${meta.command} review`, note: `${basename3(forkPath)} \xB7 last sync ${base} \u2192 upstream ${upstream}` },
+    { title: `${meta.command} review`, note: `${basename3(forkPath)} \xB7 last upgrade ${base} \u2192 upstream ${upstream}` },
     forkPath,
     `${meta.command}-review`
   );
@@ -3273,21 +3305,21 @@ async function reportReviewPage(forkPath, result, command) {
     spinnerSuccess();
   }
   if (!page) {
-    if (command === "sync") removeSyncReviewPage(forkPath);
+    if (command === "upgrade") removeSyncReviewPage(forkPath);
     return void 0;
   }
-  const opened = command === "sync" && process9.stdout.isTTY === true && openInBrowser(page.path);
+  const opened = command === "upgrade" && process9.stdout.isTTY === true && openInBrowser(page.path);
   return { ...page, command, opened };
 }
 function removeSyncReviewPage(forkPath) {
   try {
-    rmSync(diffPagePath(forkPath, "sync-review"), { force: true });
+    rmSync(diffPagePath(forkPath, "upgrade-review"), { force: true });
   } catch {
   }
 }
 function existingSyncReviewPage(forkPath) {
   try {
-    const path = diffPagePath(forkPath, "sync-review");
+    const path = diffPagePath(forkPath, "upgrade-review");
     return existsSync7(path) ? path : void 0;
   } catch {
     return void 0;
@@ -3296,9 +3328,9 @@ function existingSyncReviewPage(forkPath) {
 function reviewStep(page) {
   const path = typeof page === "string" ? page : page.path;
   const url = pathToFileURL(path).href;
-  let detail = colors_default.dim("upstream changes the sync did not bring in, from the merge run");
+  let detail = colors_default.dim("upstream changes the upgrade did not bring in, from the merge run");
   if (typeof page !== "string") {
-    const what = page.command === "sync" ? `${plural(page.diffs, "diff")} of upstream changes that did not arrive` : `${plural(page.diffs, "diff")} in ${plural(page.sections, "section")}`;
+    const what = page.command === "upgrade" ? `${plural(page.diffs, "diff")} of upstream changes that did not arrive` : `${plural(page.diffs, "diff")} in ${plural(page.sections, "section")}`;
     const notes = [
       page.listed > 0 ? `${page.listed} listed without a diff` : "",
       page.opened ? "opened in the browser" : ""
@@ -3340,8 +3372,8 @@ async function runAnalyze(config) {
       upstreamChangedLines: f.upstreamChangedLines ?? null,
       upstreamLinesAbsent: f.upstreamLinesAbsent ?? null,
       upstreamOnly: f.upstreamOnly ?? false,
-      // Only on the sync config: upstream override entries and packageJsonSync keys the fork config does not follow
-      upstreamOverrides: overrides && f.path === CONFIG_FILE ? { pinned: overrides.pinned, ignored: overrides.ignored, packageJsonSync: overrides.packageJsonSync } : null
+      // Only on the CLI config: upstream override entries and packageJsonKeys the fork config does not follow
+      upstreamOverrides: overrides && f.path === CONFIG_FILE ? { pinned: overrides.pinned, ignored: overrides.ignored, packageJsonKeys: overrides.packageJsonKeys } : null
     }));
     writeStdout(JSON.stringify(out, null, 2));
     return result;
@@ -3389,11 +3421,11 @@ function syncStep(result) {
     renamed > 0 ? `${renamed} rename` : ""
   ].filter(Boolean);
   return {
-    label: "sync",
-    line: "pnpm cella sync",
+    label: "upgrade",
+    line: "pnpm cella upgrade",
     details: [
       colors_default.dim(
-        `commits on a fresh branch, a rerun opens the PR \xB7 ${changes.length > 0 ? changes.join(", ") : "no synced file changes"}`
+        `commits on a fresh branch, a rerun opens the PR \xB7 ${changes.length > 0 ? changes.join(", ") : "no file changes"}`
       )
     ]
   };
@@ -5162,7 +5194,7 @@ import { resolve as resolve6 } from "path";
 import process10 from "process";
 import { Separator as Separator2, select as select5 } from "@inquirer/prompts";
 
-// src/services/sync.ts
+// src/services/upgrade.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import { select as select4 } from "@inquirer/prompts";
 
@@ -5176,7 +5208,7 @@ function runGh(cwd, args) {
   const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
   return { ok: result.status === 0, output };
 }
-function listOpenSyncPrs(cwd, prefix) {
+function listOpenSyncPrs(cwd, prefixes) {
   const { ok, output } = runGh(cwd, [
     "pr",
     "list",
@@ -5194,7 +5226,7 @@ function listOpenSyncPrs(cwd, prefix) {
   } catch {
     return [];
   }
-  return parsed.filter((pr) => pr.headRefName.startsWith(`${prefix}/`)).sort((a, b) => b.number - a.number);
+  return parsed.filter((pr) => prefixes.some((prefix) => pr.headRefName.startsWith(`${prefix}/`))).sort((a, b) => b.number - a.number);
 }
 function createPr(cwd, repoSlug, pr) {
   const repo = repoSlug ?? "{owner}/{repo}";
@@ -5564,8 +5596,8 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
   return { updated, changes, kept };
 }
 async function runPackages(config, options = {}) {
-  createSpinner("syncing package.json files...");
-  const keysToSync = config.settings.packageJsonSync || DEFAULT_PACKAGE_JSON_SYNC;
+  createSpinner("merging package.json files...");
+  const keysToSync = config.settings.packageJsonKeys || DEFAULT_PACKAGE_JSON_KEYS;
   const conflictedSet = new Set(options.conflictedFiles ?? []);
   const baseRef = await resolveMergeBase(config.forkPath, config.upstreamRef);
   const usage = baseRef ? await loadForkUsage(config.forkPath, config.upstreamRef, baseRef) : null;
@@ -5578,12 +5610,15 @@ async function runPackages(config, options = {}) {
       skipped.push(pkgRelPath);
       continue;
     }
-    spinnerText(`syncing ${location || "root"}/package.json...`);
+    spinnerText(`merging ${location || "root"}/package.json...`);
     const { updated, changes, kept: kept2 } = await syncPackageJson(config, baseRef, usage, location, keysToSync);
     if (updated || kept2.length > 0) reports.push({ path: pkgRelPath, changes, kept: kept2 });
   }
   const changedCount = reports.filter(({ changes }) => changes.length > 0).length;
-  spinnerSuccess("package sync complete", `${plural(changedCount, "package.json was", "package.jsons were")} changed`);
+  spinnerSuccess(
+    "package.json merge complete",
+    `${plural(changedCount, "package.json was", "package.jsons were")} changed`
+  );
   for (const { path, changes } of reports) {
     if (changes.length === 0) continue;
     console.info(`  ${path}`);
@@ -5593,7 +5628,7 @@ async function runPackages(config, options = {}) {
   const them = kept.length === 1 ? "it" : "them";
   printWarnList(`kept ${plural(kept.length, "entry", "entries")} upstream dropped, the fork still uses ${them}:`, kept);
   printWarnList(
-    `skipped ${skipped.length} conflicted package.json file(s): resolve the conflicts, commit the merge, then rerun \`pnpm cella sync\`:`,
+    `skipped ${skipped.length} conflicted package.json file(s): resolve the conflicts, commit the merge, then rerun \`pnpm cella upgrade\`:`,
     skipped
   );
 }
@@ -5604,7 +5639,7 @@ function printWarnList(header, entries) {
   for (const entry of entries) console.info(`    ${colors_default.dim("\u2192")} ${entry}`);
 }
 
-// src/services/sync.ts
+// src/services/upgrade.ts
 async function resolveCycleStart(forkPath, base, currentBranch) {
   if (!await branchExists(forkPath, base)) {
     await fetchRemote(forkPath, "origin").catch(() => {
@@ -5620,7 +5655,7 @@ async function resolveCycleStart(forkPath, base, currentBranch) {
   if (ahead > 0 && behind > 0) {
     throw new Error(
       `'${base}' has diverged from '${upstream}' (${ahead} ahead, ${behind} behind).
-Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-run sync.`
+Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-run the upgrade.`
     );
   }
   if (behind > 0) {
@@ -5649,7 +5684,7 @@ async function setupTemporarySyncBranch(config) {
   console.info(colors_default.dim(`updating '${base}'...`));
   const startPoint = await resolveCycleStart(forkPath, base, startBranch);
   const temporaryBranch = buildTemporarySyncBranch();
-  console.info(colors_default.dim(`creating temporary sync branch '${temporaryBranch}' from '${startPoint}'...`));
+  console.info(colors_default.dim(`creating temporary upgrade branch '${temporaryBranch}' from '${startPoint}'...`));
   console.info();
   await createBranchFrom(forkPath, temporaryBranch, startPoint);
   return { temporaryBranch, base, startBranch, startCommit };
@@ -5673,7 +5708,7 @@ async function returnToBase(forkPath, base) {
   return `back on '${base}'`;
 }
 async function runSync(config, options) {
-  createSpinner("starting sync...");
+  createSpinner("starting upgrade...");
   let result;
   try {
     result = await runEngineWithSpinner(config, true);
@@ -5688,7 +5723,7 @@ async function runSync(config, options) {
   if (result.success) {
     spinnerSuccess();
   } else {
-    spinnerFail("sync completed with conflicts");
+    spinnerFail("upgrade merge completed with conflicts");
   }
   printEngineReports(result, "merge summary");
   if (config.unpinned) {
@@ -5698,7 +5733,7 @@ async function runSync(config, options) {
   const staged = result.files.some((file) => SYNC_APPLIED_STATUSES.includes(file.status));
   const stagedBranch = options?.stagedBranch && result.conflicts.length === 0 && staged ? options.stagedBranch : void 0;
   printSyncComplete(result, { stagedBranch });
-  const reviewPage = await reportReviewPage(config.forkPath, result, "sync");
+  const reviewPage = await reportReviewPage(config.forkPath, result, "upgrade");
   return { ...result, reviewPage };
 }
 var CONFLICTS_LISTED = 10;
@@ -5725,9 +5760,9 @@ async function conflictSteps(config, conflicts, run) {
     },
     {
       label: "finish",
-      line: "pnpm cella sync",
+      line: "pnpm cella upgrade",
       details: [
-        colors_default.dim("commits the sync and stops for drift triage"),
+        colors_default.dim("commits the upgrade and stops for drift triage"),
         colors_default.dim("let the rerun commit: a manual `git commit` records a merge commit that bloats the PR")
       ]
     },
@@ -5736,13 +5771,13 @@ async function conflictSteps(config, conflicts, run) {
   ];
   return steps.filter((step) => !!step);
 }
-var SYNC_PR_TITLE = "chore: sync upstream cella";
+var UPGRADE_PR_TITLE = "chore: upgrade cella";
 async function buildSyncCommitMessage(forkPath, upstreamRef) {
   const shortSha = await getShortSha(forkPath, upstreamRef).catch(() => "");
-  if (!shortSha) return SYNC_PR_TITLE;
+  if (!shortSha) return UPGRADE_PR_TITLE;
   const manifest = await readSyncManifest(forkPath);
   const version = manifest?.upstream.release ?? await readPackageVersionAtRef(forkPath, upstreamRef).catch(() => null);
-  return version ? `${SYNC_PR_TITLE} v${version.replace(/^v/, "")} (${shortSha})` : `${SYNC_PR_TITLE} ${shortSha}`;
+  return version ? `${UPGRADE_PR_TITLE} to v${version.replace(/^v/, "")} (${shortSha})` : `${UPGRADE_PR_TITLE} to ${shortSha}`;
 }
 function qualifyPrRefs(subject, repoSlug) {
   if (!repoSlug) return subject;
@@ -5755,10 +5790,14 @@ function buildSyncPrBody(input) {
   const commitRef = (sha) => githubUrl ? `[\`${short(sha)}\`](${githubUrl}/commit/${sha})` : `\`${short(sha)}\``;
   const upstreamName = githubUrl ? `[${repoSlug}](${githubUrl})` : "cella";
   const versionSuffix = version ? ` (v${version.replace(/^v/, "")})` : "";
-  const lines = [`Syncs upstream ${upstreamName} to ${commitRef(toSha)}${versionSuffix}.`];
+  const lines = [`Upgrades ${upstreamName} to ${commitRef(toSha)}${versionSuffix}.`];
   if (totalCount > 0 && fromSha) {
     const compare = githubUrl ? ` ([compare](${githubUrl}/compare/${short(fromSha)}...${short(toSha)}))` : "";
-    lines.push("", `**${totalCount} upstream commit${totalCount === 1 ? "" : "s"} since last sync**${compare}:`, "");
+    lines.push(
+      "",
+      `**${totalCount} upstream commit${totalCount === 1 ? "" : "s"} since the last upgrade**${compare}:`,
+      ""
+    );
     if (totalCount > commits.length) lines.push(`- \u2026${totalCount - commits.length} earlier commit(s) not shown`);
     for (const commit of commits) {
       lines.push(`- ${commitRef(commit.hash)} ${qualifyPrRefs(commit.message, repoSlug)}`);
@@ -5813,7 +5852,7 @@ async function readPrBodyAlignments(forkPath, toSha, repoSlug) {
   );
   return { total: ids.length, open };
 }
-function printPrCreateStep(branch, base, title = SYNC_PR_TITLE) {
+function printPrCreateStep(branch, base, title = UPGRADE_PR_TITLE) {
   console.info(colors_default.dim(`  gh pr create --base ${base} --head ${branch} --title "${title}" --fill`));
 }
 async function flattenSyncBranch(forkPath, branch, base) {
@@ -5837,7 +5876,7 @@ async function shipSyncBranch(config, branch) {
   let prUrl;
   let prOpened = false;
   const upstreamCommit = (await readSyncManifest(forkPath))?.upstream.commit;
-  const prTitle = upstreamCommit ? await buildSyncCommitMessage(forkPath, upstreamCommit) : SYNC_PR_TITLE;
+  const prTitle = upstreamCommit ? await buildSyncCommitMessage(forkPath, upstreamCommit) : UPGRADE_PR_TITLE;
   console.info(colors_default.dim(`pushing '${branch}' to origin...`));
   try {
     await pushBranch(forkPath, "origin", branch, { forceWithLease: flattened });
@@ -5866,17 +5905,17 @@ async function shipSyncBranch(config, branch) {
   const position = await returnToBase(forkPath, base);
   console.info();
   if (prUrl) {
-    console.info(`${checkMark} sync pull request ${prOpened ? "opened" : "ready"}`);
+    console.info(`${checkMark} upgrade pull request ${prOpened ? "opened" : "ready"}`);
     console.info(colors_default.dim(`  ${prUrl} \xB7 branch pushed, ${position}`));
   } else {
-    console.info(`${checkMark} sync branch pushed`);
+    console.info(`${checkMark} upgrade branch pushed`);
     console.info(colors_default.dim(`  '${branch}' is on origin, ${position}`));
   }
   const steps = [
     prUrl ? {
       label: "merge",
       line: hyperlink(colors_default.cyan(prUrl), prUrl),
-      details: [colors_default.dim(`squash-merge it into '${base}'; the next sync offers to while it is open`)]
+      details: [colors_default.dim(`squash-merge it into '${base}'; the next upgrade offers to while it is open`)]
     } : void 0,
     await syncAlignmentsStep(config)
   ];
@@ -5916,7 +5955,7 @@ async function runSyncCycle(config) {
     }
     throw error;
   }
-  if (config.settings.syncWithPackages !== false) {
+  if (config.settings.mergePackageJson !== false) {
     await runPackages(config, { conflictedFiles: result.conflicts });
   }
   if (result.conflicts.length > 0) return { status: "conflicts", branch, result };
@@ -5941,7 +5980,11 @@ async function commitSyncMerge(config, branch, run) {
     printStep("checks", "`pnpm install` or `pnpm check` failed", warningMark);
     printNextSteps([
       { label: "fix", line: "what failed above", details: [colors_default.dim(`the merge stays staged on '${branch}'`)] },
-      { label: "finish", line: "pnpm cella sync", details: [colors_default.dim("commits the sync and stops for drift triage")] }
+      {
+        label: "finish",
+        line: "pnpm cella upgrade",
+        details: [colors_default.dim("commits the upgrade and stops for drift triage")]
+      }
     ]);
     return;
   }
@@ -5959,7 +6002,7 @@ ${colors_default.dim(`on '${branch}', not pushed`)}`);
       details: [colors_default.dim("drift triage: commit any follow-ups on this branch")]
     },
     await syncAlignmentsStep(config, run),
-    { label: "ship", line: "pnpm cella sync", details: [colors_default.dim("pushes the branch and opens the squash-merge PR")] }
+    { label: "ship", line: "pnpm cella upgrade", details: [colors_default.dim("pushes the branch and opens the squash-merge PR")] }
   ];
   printNextSteps(steps.filter((step) => !!step));
 }
@@ -5972,7 +6015,7 @@ async function mergeOpenSyncPrs(config, open) {
   const merged = mergePrSquash(forkPath, newest.number, { deleteBranch: true });
   if (!merged.ok) {
     console.info();
-    console.info(colors_default.yellow(`could not merge #${newest.number}: resolve it first, then re-run \`pnpm cella sync\`:`));
+    console.info(colors_default.yellow(`could not merge #${newest.number}: resolve it first, then re-run \`pnpm cella upgrade\`:`));
     if (merged.output) console.info(colors_default.dim(merged.output.replace(/^/gm, "  ")));
     console.info(colors_default.dim(`  ${newest.url}`));
     return "cancel";
@@ -5989,25 +6032,27 @@ async function mergeOpenSyncPrs(config, open) {
 async function guardAgainstOpenSyncPr(config) {
   const { forkPath } = config;
   if (!ghAvailable() || !process.stdout.isTTY) return "continue";
-  const open = listOpenSyncPrs(forkPath, DEFAULT_SYNC_PREFIX);
+  const open = listOpenSyncPrs(forkPath, TEMPORARY_BRANCH_PREFIXES);
   if (open.length === 0) return "continue";
   const many = open.length > 1;
   console.info();
   console.info(
-    `${warningMark} ${colors_default.yellow(`${many ? `${open.length} earlier sync PRs are` : "an earlier sync PR is"} still open and unmerged:`)}`
+    `${warningMark} ${colors_default.yellow(`${many ? `${open.length} earlier upgrade PRs are` : "an earlier upgrade PR is"} still open and unmerged:`)}`
   );
   for (const pr of open) {
     console.info(colors_default.dim(`  #${pr.number}  ${pr.title}`));
     console.info(colors_default.dim(`         ${pr.url}`));
   }
-  console.info(colors_default.dim(`  starting a new sync now produces a PR that re-includes ${many ? "these" : "those"} changes.`));
+  console.info(
+    colors_default.dim(`  starting a new upgrade now produces a PR that re-includes ${many ? "these" : "those"} changes.`)
+  );
   console.info();
   const choice = await select4({
     message: "how do you want to proceed?",
     choices: [
       {
         value: "merge",
-        name: `merge ${many ? "them" : `#${open[0].number}`} first, then sync   ${colors_default.dim("(recommended)")}`
+        name: `merge ${many ? "them" : `#${open[0].number}`} first, then upgrade   ${colors_default.dim("(recommended)")}`
       },
       { value: "continue", name: `continue anyway   ${colors_default.dim("(new PR will re-include the unmerged changes)")}` },
       { value: "cancel", name: colors_default.red("cancel") }
@@ -6018,7 +6063,7 @@ async function guardAgainstOpenSyncPr(config) {
   if (choice === "continue") return "continue";
   return mergeOpenSyncPrs(config, open);
 }
-async function runSyncCommand(config) {
+async function runUpgradeCommand(config) {
   const { forkPath } = config;
   const currentBranch = await getCurrentBranch(forkPath);
   const onSyncBranch = isTemporarySyncBranch(currentBranch);
@@ -6031,7 +6076,7 @@ async function runSyncCommand(config) {
       console.info();
       console.info(
         colors_default.yellow(
-          `sync branch '${currentBranch}' has uncommitted changes.
+          `upgrade branch '${currentBranch}' has uncommitted changes.
 commit them first (\`git commit --amend --no-edit\` or a new commit).`
         )
       );
@@ -6041,17 +6086,17 @@ commit them first (\`git commit --amend --no-edit\` or a new commit).`
     return;
   }
   if (!await isClean(forkPath)) {
-    throw new Error("working directory has uncommitted changes. please commit or stash before syncing.");
+    throw new Error("working directory has uncommitted changes. please commit or stash before upgrading.");
   }
   if (await guardAgainstOpenSyncPr(config) === "cancel") return;
   const outcome = await runSyncCycle(config);
   if (outcome.status === "noop") {
     console.info();
     if (outcome.behind) {
-      console.info(colors_default.green("nothing to sync: the last sync already went past this upstream point."));
+      console.info(colors_default.green("nothing to upgrade: the last upgrade already went past this upstream point."));
       for (const line of outcome.behind.split("\n")) console.info(colors_default.dim(`  ${line}`));
     } else {
-      console.info(colors_default.green("already up to date with upstream, nothing to sync."));
+      console.info(colors_default.green("already up to date with upstream, nothing to upgrade."));
     }
     const align = await syncAlignmentsStep(config, outcome.result);
     if (align) printNextSteps([align]);
@@ -6089,7 +6134,7 @@ function formatForkChoice(name, status) {
     syncPart = colors_default.dim(`${status.lastSync.date}`);
     if (msg) syncPart += colors_default.dim(` '${msg}'`);
   } else {
-    syncPart = colors_default.dim("never synced");
+    syncPart = colors_default.dim("never upgraded");
   }
   const dirtyPart = status.dirty > 0 ? colors_default.yellow(`${status.dirty} uncommitted`) : "";
   const parts = [name, colors_default.dim(`[${status.branch}]`), syncPart];
@@ -6121,15 +6166,15 @@ async function buildForkChoices(forks, basePath) {
 }
 async function syncFork(config, fork, forkPath) {
   console.info();
-  console.info(colors_default.cyan(`syncing to ${fork.name}...`));
+  console.info(colors_default.cyan(`upgrading ${fork.name}...`));
   console.info(colors_default.dim(`path: ${forkPath}`));
   console.info();
   const forkConfig = await loadConfig(forkPath);
-  await runSyncCommand({
+  await runUpgradeCommand({
     ...forkConfig,
     forkPath,
     upstreamRef: resolveUpstream(forkConfig.settings).branchRef,
-    service: "sync",
+    service: "upgrade",
     list: false,
     json: false,
     verbose: false,
@@ -6156,7 +6201,7 @@ async function runForks(config) {
     const choices = await buildForkChoices(forks, forkBasePath);
     const forkChoices = [...choices, new Separator2(MENU_DIVIDER), { value: "_exit", name: colors_default.dim("exit") }];
     const selectedPath = await select5({
-      message: "select fork to sync:",
+      message: "select fork to upgrade:",
       choices: forkChoices,
       loop: false
     });
@@ -6620,7 +6665,7 @@ function preflight(forkPath) {
 }
 var services = {
   analyze: runAnalyze,
-  sync: runSyncCommand,
+  upgrade: runUpgradeCommand,
   align: runAlign,
   audit: runAudit,
   forks: runForks,