@cellajs/cli 0.3.1 → 0.3.3

package/dist/index.js

@@ -2,12 +2,10 @@
 
 // src/cella-cli.ts
 import { existsSync as existsSync13, statSync as statSync3 } from "fs";
-import { join as join21, resolve as resolve8 } from "path";
+import { join as join19, resolve as resolve8 } from "path";
 import process9 from "process";
 
 // src/cli.ts
-import { readFileSync } from "fs";
-import { join as join8 } from "path";
 import process5 from "process";
 import { select } from "@inquirer/prompts";
 import { Command } from "commander";
@@ -53,32 +51,31 @@ var pc = {
 var colors_default = pc;
 
 // src/utils/config.ts
-import { existsSync as existsSync2, realpathSync } from "fs";
+import { existsSync as existsSync2, readFileSync, realpathSync } from "fs";
 import { join as join2, resolve } from "path";
 import { z as z2 } from "zod";
 
 // src/config/types.ts
 import { z } from "zod";
+var PACKAGE_JSON_SYNC_KEYS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "scripts",
+  "engines",
+  "packageManager",
+  "overrides",
+  "exports",
+  "pnpm"
+];
 var cellaConfigSchema = z.object({
   settings: z.object({
     upstreamUrl: z.string().min(1),
     upstreamBranch: z.string().min(1).optional(),
     upstreamTrack: z.enum(["release", "branch"]).optional(),
     releaseBase: z.string().min(1).optional(),
-    packageJsonSync: z.array(
-      z.enum([
-        "dependencies",
-        "devDependencies",
-        "peerDependencies",
-        "optionalDependencies",
-        "scripts",
-        "engines",
-        "packageManager",
-        "overrides",
-        "exports",
-        "pnpm"
-      ])
-    ).optional(),
+    packageJsonSync: z.array(z.enum(PACKAGE_JSON_SYNC_KEYS)).optional(),
     syncWithPackages: z.boolean().optional(),
     fileLinkMode: z.enum(["commit", "file", "local"]).optional()
   }).strict(),
@@ -95,6 +92,12 @@ var cellaConfigSchema = z.object({
     }).strict()
   ).optional()
 }).strict();
+var SYNC_APPLIED_STATUSES = ["behind", "diverged", "renamed", "ignored", "pinned"];
+
+// src/utils/errors.ts
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
 // src/utils/managed-files.ts
 var CONFIG_FILE = "cella/cella.config.ts";
@@ -160,6 +163,10 @@ var DEFAULT_UPSTREAM_REMOTE = "cella-upstream";
 var DEFAULT_BRANCH = "main";
 var DEFAULT_SYNC_PREFIX = "cella/sync";
 var DEFAULT_RELEASE_BASE = "main";
+var DEFAULT_PACKAGE_JSON_SYNC = ["dependencies", "devDependencies"];
+function isUpstreamRepo(repoPath) {
+  return JSON.parse(readFileSync(join2(repoPath, "package.json"), "utf8")).name === "cella";
+}
 function isTemporarySyncBranch(branch) {
   return branch.startsWith(`${DEFAULT_SYNC_PREFIX}/`);
 }
@@ -192,8 +199,7 @@ async function loadConfig(forkPath) {
   try {
     configModule = await import(realConfigPath);
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`failed to load ${configPath}: ${message}`);
+    throw new Error(`failed to load ${configPath}: ${errorMessage(error)}`);
   }
   const result = cellaConfigSchema.safeParse(configModule.default);
   if (!result.success) {
@@ -220,7 +226,7 @@ import process4 from "process";
 // package.json
 var package_default = {
   name: "@cellajs/cli",
-  version: "0.3.1",
+  version: "0.3.3",
   private: false,
   license: "MIT",
   description: "CLI for managing your monorepo and syncing with upstream Cella.",
@@ -346,6 +352,8 @@ var package_default = {
 var NAME = "cella cli";
 var VERSION = package_default.version;
 var DIVIDER = "\u2500".repeat(60);
+var MENU_DIVIDER = "\u2500".repeat(40);
+var COMMIT_LIST_MAX = 50;
 var warningMark = colors_default.yellow("\u26A0");
 var checkMark = colors_default.green("\u2713");
 var TerminalSpinner = class {
@@ -454,7 +462,7 @@ function getVsCodeOpenFileLink(filePath, options) {
   const url = `vscode://file${absolutePath}`;
   return hyperlink(filePath, url);
 }
-function formatFetchedUpstreamDetail(commitCount, commits, upstreamGitHubUrl, maxShownCommits = 50) {
+function formatFetchedUpstreamDetail(commitCount, commits, upstreamGitHubUrl, maxShownCommits = COMMIT_LIST_MAX) {
   const commitLabel = commitCount === 1 ? "1 new commit" : `${commitCount} new commits`;
   const lines = [`${commitLabel} since last merge`];
   const shown = commits.slice(0, maxShownCommits);
@@ -538,19 +546,7 @@ var summaryStatusConfig = {
 var statusOrder = Object.keys(statusConfig);
 function printSummary(summary, title = "summary") {
   printSectionHeader(colors_default.cyan(title));
-  const maxCount = Math.max(
-    summary.managed,
-    summary.ignored,
-    summary.identical,
-    summary.ahead,
-    summary.local,
-    summary.drifted,
-    summary.behind,
-    summary.diverged,
-    summary.pinned,
-    summary.deleted,
-    summary.renamed
-  );
+  const maxCount = Math.max(...statusOrder.map((status) => summary[status]), summary.managed);
   const countWidth = String(maxCount).length + 1;
   const printLine = (status, count) => {
     const { icon, label, color, description } = summaryStatusConfig[status];
@@ -613,11 +609,23 @@ function formatUpstreamChangedLines(file) {
   const n = file.upstreamChangedLines;
   return colors_default.yellow(` \xB7 ${n} ${n === 1 ? "line" : "lines"} changed upstream`);
 }
+function protectedDiffHints(source, paths) {
+  const range = source?.upstreamDiffRange;
+  if (!range) return [];
+  const listed = new Set(paths);
+  const groups = (source?.protectedUpstreamChanges ?? []).filter((group) => group.paths.some((p) => listed.has(p)));
+  if (groups.length === 0) return [];
+  return [
+    "what upstream changed since the last sync, per pinned/ignored entry:",
+    ...groups.map((group) => `  git diff ${range} -- ${shellPath(group.entry)}`)
+  ];
+}
 function formatUpstreamLinesAbsent(file) {
   const n = file.upstreamLinesAbsent ?? 0;
   return n > 0 ? colors_default.yellow(` \xB7 ${n} upstream ${n === 1 ? "line" : "lines"} absent`) : "";
 }
-function printAnalysisFileGroups(files, linkOptions) {
+function printAnalysisFileGroups(files, linkOptions, diffSource) {
+  const protectedBehind = findProtectedBehind(files);
   printFileGroup(files, "behind", linkOptions, {
     title: colors_default.cyan("\u2193 behind on upstream")
   });
@@ -629,17 +637,18 @@ function printAnalysisFileGroups(files, linkOptions) {
       "pinned files keep the fork side on every conflict; a count here is upstream content the fork never received, deliberately or not: diff and decide."
     ]
   });
-  printFileSection(
-    findProtectedBehind(files),
-    `${warningMark} ${colors_default.yellow("protected but behind upstream")}`,
-    linkOptions,
-    {
-      icon: protectionIcon,
-      suffix: formatUpstreamChangedLines,
-      dateSource: "upstream",
-      hint: PROTECTED_BEHIND_HINT
-    }
-  );
+  printFileSection(protectedBehind, `${warningMark} ${colors_default.yellow("protected but behind upstream")}`, linkOptions, {
+    icon: protectionIcon,
+    suffix: formatUpstreamChangedLines,
+    dateSource: "upstream",
+    hint: [
+      PROTECTED_BEHIND_HINT,
+      ...protectedDiffHints(
+        diffSource,
+        protectedBehind.map((file) => file.path)
+      )
+    ]
+  });
   printFileGroup(files, "drifted", linkOptions, {
     title: `${warningMark} ${colors_default.yellow("drifted from upstream")}`,
     hint: "these files have fork changes but are not pinned or ignored."
@@ -653,7 +662,7 @@ function printAnalysisFileGroups(files, linkOptions) {
 function writeLogFile(forkPath, files) {
   const logPath = join3(forkPath, "cella-sync.log");
   const lines = [
-    `cella sync analysis - ${(/* @__PURE__ */ new Date()).toISOString()}`,
+    `cella sync analysis: ${(/* @__PURE__ */ new Date()).toISOString()}`,
     DIVIDER,
     "",
     `complete file list (${files.length} files)`,
@@ -671,7 +680,7 @@ function writeLogFile(forkPath, files) {
     const icon = config.icon.replace(/\x1b\[[0-9;]*m/g, "");
     lines.push(`  ${icon} ${config.label.padEnd(12)} ${file.path}`);
   }
-  writeFileSync(logPath, lines.join("\n"), "utf-8");
+  writeFileSync(logPath, lines.join("\n"), "utf8");
   return logPath;
 }
 function printSyncComplete(result, options = {}) {
@@ -681,12 +690,12 @@ function printSyncComplete(result, options = {}) {
   const conflicts = result.conflicts.length;
   console.info();
   if (options.stagedBranch) {
-    console.info(`${colors_default.green("\u2713")} Sync merge staged on '${options.stagedBranch}'`);
+    console.info(`${checkMark} sync merge staged on '${options.stagedBranch}'`);
     console.info(
-      colors_default.dim(`  ${updated} files updated, ${merged} auto-merged, ${conflicts} conflicts. Committing next...`)
+      colors_default.dim(`  ${updated} files updated, ${merged} auto-merged, ${conflicts} conflicts. committing next...`)
     );
   } else {
-    console.info(`${colors_default.green("\u2713")} sync complete`);
+    console.info(`${checkMark} sync complete`);
     console.info(colors_default.dim(`  ${updated} files updated, ${merged} auto-merged, ${conflicts} conflicts`));
   }
   printProtectedConflicts(result);
@@ -702,18 +711,18 @@ function printProtectedConflicts(result) {
       `${paths.length} protected ${paths.length === 1 ? "file kept" : "files kept"} the fork version, dropping upstream changes:`
     )}`
   );
-  for (const path4 of paths) {
-    const file = byPath.get(path4);
+  for (const path of paths) {
+    const file = byPath.get(path);
     const icon = file ? protectionIcon(file) : statusConfig.pinned.icon;
-    console.info(`  ${icon} ${path4}${file ? formatUpstreamChangedLines(file) : ""}`);
+    console.info(`  ${icon} ${path}${file ? formatUpstreamChangedLines(file) : ""}`);
   }
-  console.info(colors_default.dim(`  ${PROTECTED_BEHIND_HINT}`));
+  for (const line of [PROTECTED_BEHIND_HINT, ...protectedDiffHints(result, paths)]) console.info(colors_default.dim(`  ${line}`));
 }
 function plural(count, singular, pluralForm = `${singular}s`) {
   return `${count} ${count === 1 ? singular : pluralForm}`;
 }
-function shellPath(path4) {
-  return /^[\w./@+-]+$/.test(path4) ? path4 : `'${path4.replace(/'/g, `'\\''`)}'`;
+function shellPath(path) {
+  return /^[\w./@+-]+$/.test(path) ? path : `'${path.replace(/'/g, `'\\''`)}'`;
 }
 function printIgnoredUpstreamChanges(result) {
   const groups = result.ignoredUpstreamChanges ?? [];
@@ -741,19 +750,19 @@ function printUpstreamOverrideChanges(result) {
   if (report.kind === "unreadable") {
     const side = report.side === "base" ? "the last sync point" : "the incoming ref";
     console.info(
-      colors_default.dim(`upstream overrides not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
+      colors_default.dim(`upstream sync config not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
     );
     return;
   }
   const lines = [];
-  for (const list of ["pinned", "ignored"]) {
+  for (const list of ["pinned", "ignored", "packageJsonSync"]) {
     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 overrides \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
+    `${warningMark} ${colors_default.yellow(`upstream changed its sync 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.`));
@@ -770,7 +779,7 @@ function printMaskingPinWarning(files) {
   console.info();
   console.info(
     `${warningMark} ${colors_default.yellow(
-      `${masking.length} pinned ${many ? "files match" : "file matches"} the previous upstream but changed upstream \u2014`
+      `${masking.length} pinned ${many ? "files match" : "file matches"} the previous upstream but changed upstream:`
     )}`
   );
   console.info(colors_default.yellow("  the pin keeps the old fork copy and silently drops those upstream changes:"));
@@ -778,7 +787,7 @@ function printMaskingPinWarning(files) {
     console.info(colors_default.dim(`  \u2A00 ${file.path}`));
   }
   console.info(
-    colors_default.yellow("  If the fork never customized these, unpin them in cella/cella.config.ts to take upstream.")
+    colors_default.yellow("  if the fork never customized these, unpin them in cella/cella.config.ts to take upstream.")
   );
   console.info();
 }
@@ -795,19 +804,26 @@ function printFlagWarnings(options) {
       )
     );
   }
-  console.info(colors_default.yellow("  Be extra careful & cherrypick what you want only."));
+  console.info(colors_default.yellow("  be extra careful and cherry-pick what you want only."));
   console.info();
 }
+function printEngineReports(result, title) {
+  printSummary(result.summary, title);
+  printIgnoredUpstreamChanges(result);
+  printUpstreamOverrideChanges(result);
+  printMaskingPinWarning(result.files);
+}
+function printLogFileReport(config, files) {
+  if (!config.logFile) return;
+  const logPath = writeLogFile(config.forkPath, files);
+  console.info();
+  console.info(colors_default.dim(`full file list written to: ${logPath}`));
+}
 
 // src/utils/overrides.ts
 import { existsSync as existsSync5 } from "fs";
 import { join as join7 } from "path";
 
-// src/utils/migration-notes.ts
-import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir3, readFile as readFile2, rm, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname3, join as join6 } from "path";
-
 // src/utils/git.ts
 import { execFile } from "child_process";
 import { existsSync as existsSync3 } from "fs";
@@ -819,9 +835,9 @@ import { promisify } from "util";
 import { mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join as join4 } from "path";
 var MANIFEST_FILE = "cella/cella.manifest.json";
-async function readSyncManifest(cwd) {
+function parseSyncManifest(raw) {
   try {
-    const parsed = JSON.parse(await readFile(join4(cwd, MANIFEST_FILE), "utf8"));
+    const parsed = JSON.parse(raw);
     const commit = parsed?.upstream?.commit;
     if (typeof commit !== "string" || !/^[0-9a-f]{40}$/i.test(commit)) return null;
     return parsed;
@@ -829,6 +845,13 @@ async function readSyncManifest(cwd) {
     return null;
   }
 }
+async function readSyncManifest(cwd) {
+  try {
+    return parseSyncManifest(await readFile(join4(cwd, MANIFEST_FILE), "utf8"));
+  } catch {
+    return null;
+  }
+}
 async function readManifestBase(cwd) {
   const manifest = await readSyncManifest(cwd);
   return manifest ? manifest.upstream.commit.toLowerCase() : null;
@@ -842,7 +865,8 @@ async function writeSyncManifest(cwd, manifest) {
 
 // src/utils/git.ts
 var execFileAsync = promisify(execFile);
-function sanitizeCredentials(text) {
+var MAX_BUFFER = 50 * 1024 * 1024;
+function redactUrlSecrets(text) {
   return text.replace(/https?:\/\/[^@\s]+@/g, (match) => {
     const protocol = match.startsWith("https") ? "https" : "http";
     return `${protocol}://***@`;
@@ -854,14 +878,14 @@ async function git(args, cwd, options = {}) {
     ...options.skipEditor ? { GIT_EDITOR: "true" } : {},
     ...options.env
   };
-  const maxBuffer = options.maxBuffer ?? 50 * 1024 * 1024;
+  const maxBuffer = options.maxBuffer ?? MAX_BUFFER;
   try {
     const { stdout } = await execFileAsync("git", args, { cwd, env, maxBuffer });
     return stdout.trim();
   } catch (error) {
     if (options.ignoreErrors) return "";
     if (error instanceof Error) {
-      error.message = sanitizeCredentials(error.message);
+      error.message = redactUrlSecrets(error.message);
     }
     throw error;
   }
@@ -932,8 +956,8 @@ async function flattenBranch(cwd, baseRef, message) {
 }
 async function commitSquash(cwd, message) {
   for (const file of ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE"]) {
-    const path4 = await gitPath(cwd, file);
-    if (existsSync3(path4)) await unlink(path4);
+    const path = await gitPath(cwd, file);
+    if (existsSync3(path)) await unlink(path);
   }
   await git(["commit", "-m", message], cwd, { skipEditor: true });
 }
@@ -965,12 +989,13 @@ async function ensureRemote(cwd, remoteName, url) {
     await git(["remote", "add", remoteName, url], cwd);
   }
 }
-async function fetch2(cwd, remoteName) {
+async function fetchRemote(cwd, remoteName) {
   await git(["fetch", remoteName], cwd);
 }
 async function fetchUpstreamTags(cwd, remoteName) {
   await git(["fetch", remoteName, "--no-tags", `+refs/tags/*:refs/${remoteName}/tags/*`], cwd);
 }
+var releaseTagPattern = /^v?\d[\w.+-]*$/;
 async function resolveLatestReleaseTag(cwd, remoteName) {
   const prefix = `refs/${remoteName}/tags/`;
   const output = await git(["for-each-ref", "--sort=-version:refname", "--format=%(refname)", prefix], cwd, {
@@ -981,7 +1006,7 @@ async function resolveLatestReleaseTag(cwd, remoteName) {
     const ref = line.trim();
     if (!ref) continue;
     const tag = ref.slice(prefix.length);
-    if (/^v\d/.test(tag)) return { tag, ref };
+    if (releaseTagPattern.test(tag)) return { tag, ref };
   }
   return null;
 }
@@ -991,7 +1016,7 @@ async function resolveUpstreamCommit(cwd, remoteName, ref) {
   for (const candidate of [`refs/remotes/${remoteName}/${ref}`, tagRef, ref]) {
     const sha = await git(["rev-parse", "-q", "--verify", `${candidate}^{commit}`], cwd, { ignoreErrors: true });
     if (!sha) continue;
-    const release = candidate === tagRef && /^v\d[\w.+-]*$/.test(ref) ? { tag: ref, ref: tagRef } : void 0;
+    const release = candidate === tagRef && releaseTagPattern.test(ref) ? { tag: ref, ref: tagRef } : void 0;
     return { sha, release };
   }
   return null;
@@ -1005,7 +1030,8 @@ async function isPublishedUpstream(cwd, remoteName, branchRef, sha) {
       "--contains",
       sha,
       `refs/remotes/${branchRef}`,
-      `refs/${remoteName}/tags/v*`
+      `refs/${remoteName}/tags/[0-9]*`,
+      `refs/${remoteName}/tags/v[0-9]*`
     ],
     cwd,
     { ignoreErrors: true }
@@ -1023,10 +1049,8 @@ async function countCommitsBetween(cwd, fromRef, toRef) {
   return Number.parseInt(output.trim(), 10) || 0;
 }
 async function listCommitsBetween(cwd, fromRef, toRef, options = {}) {
-  const { oldestFirst = true, skip = 0, limit } = options;
-  const args = ["log", "--format=%H%x1f%s%x1f%ar"];
-  if (oldestFirst) args.push("--reverse");
-  args.push(`${fromRef}..${toRef}`);
+  const { skip, limit } = options;
+  const args = ["log", "--format=%H%x1f%s%x1f%ar", "--reverse", `${fromRef}..${toRef}`];
   const output = await git(args, cwd, { ignoreErrors: true });
   if (!output) return [];
   const commits = [];
@@ -1036,14 +1060,8 @@ async function listCommitsBetween(cwd, fromRef, toRef, options = {}) {
     if (!hash || !message || !date) continue;
     commits.push({ hash, message, date });
   }
-  const normalizedSkip = Math.max(0, skip);
-  const normalizedLimit = typeof limit === "number" && limit > 0 ? limit : void 0;
-  if (normalizedSkip === 0 && normalizedLimit === void 0) {
-    return commits;
-  }
-  const start = Math.min(normalizedSkip, commits.length);
-  const end = normalizedLimit === void 0 ? commits.length : Math.min(start + normalizedLimit, commits.length);
-  return commits.slice(start, end);
+  const start = Math.max(0, skip ?? 0);
+  return limit && limit > 0 ? commits.slice(start, start + limit) : commits.slice(start);
 }
 async function getFileChangeInfo(cwd, fromRef, toRef) {
   const info = /* @__PURE__ */ new Map();
@@ -1098,12 +1116,9 @@ async function listWorktrees(cwd) {
   }
   return paths;
 }
-async function merge(cwd, ref, options = {}) {
-  const args = ["merge", "--no-ff", ref];
-  if (options.noCommit) args.push("--no-commit");
-  if (options.noEdit) args.push("--no-edit");
+async function merge(cwd, ref) {
   try {
-    await git(args, cwd, { skipEditor: true });
+    await git(["merge", "--no-ff", "--no-commit", "--no-edit", ref], cwd, { skipEditor: true });
     return { success: true, conflicts: [] };
   } catch (error) {
     const conflicts = await getConflictedFiles(cwd);
@@ -1131,6 +1146,22 @@ async function checkoutFromRef(cwd, ref, filePath) {
 async function restoreWorktreeFromRef(cwd, ref, filePath) {
   await git(["restore", `--source=${ref}`, "--worktree", "--", filePath], cwd);
 }
+async function batchRestoreWorktreeFromRef(cwd, ref, filePaths) {
+  const batchSize = 200;
+  for (let i = 0; i < filePaths.length; i += batchSize) {
+    const batch = filePaths.slice(i, i + batchSize);
+    await git(["--literal-pathspecs", "restore", `--source=${ref}`, "--worktree", "--", ...batch], cwd);
+  }
+}
+async function listIdenticalToRef(cwd, ref) {
+  const nulSeparated = (out) => out.split("\0").filter(Boolean);
+  const [tracked, changed] = await Promise.all([
+    git(["ls-tree", "-r", "--name-only", "-z", ref], cwd),
+    git(["diff", "--name-only", "--no-renames", "-z", ref, "--"], cwd)
+  ]);
+  const differs = new Set(nulSeparated(changed));
+  return new Set(nulSeparated(tracked).filter((path) => !differs.has(path)));
+}
 async function getMergeBase(cwd, ref1, ref2) {
   return git(["merge-base", ref1, ref2], cwd);
 }
@@ -1140,6 +1171,7 @@ async function getFileChanges(cwd, baseRef, targetRef) {
   });
   const changes = /* @__PURE__ */ new Map();
   if (!output) return changes;
+  const hashOrNull = (hash) => hash === "0".repeat(40) ? null : hash;
   for (const line of output.split("\n")) {
     if (!line) continue;
     const renameMatch = line.match(/^:\d+ \d+ ([a-f0-9]+) ([a-f0-9]+) R\d*\s+(.+)\t(.+)$/);
@@ -1147,10 +1179,9 @@ async function getFileChanges(cwd, baseRef, targetRef) {
       const [, baseHash, targetHash, oldPath, newPath] = renameMatch;
       changes.set(newPath, {
         status: "R",
-        baseHash: baseHash === "0".repeat(40) ? null : baseHash,
-        targetHash: targetHash === "0".repeat(40) ? null : targetHash,
-        oldPath,
-        newPath
+        baseHash: hashOrNull(baseHash),
+        targetHash: hashOrNull(targetHash),
+        oldPath
       });
       continue;
     }
@@ -1159,8 +1190,8 @@ async function getFileChanges(cwd, baseRef, targetRef) {
       const [, baseHash, targetHash, status, filePath] = match;
       changes.set(filePath, {
         status,
-        baseHash: baseHash === "0".repeat(40) ? null : baseHash,
-        targetHash: targetHash === "0".repeat(40) ? null : targetHash
+        baseHash: hashOrNull(baseHash),
+        targetHash: hashOrNull(targetHash)
       });
     }
   }
@@ -1174,9 +1205,9 @@ async function getDiffStat(cwd, fromRef, toRef, paths = []) {
   for (const line of out.split("\n")) {
     if (!line.trim()) continue;
     const [a, d, ...rest] = line.split("	");
-    const path4 = rest.join("	");
-    if (!path4) continue;
-    stat.set(path4, {
+    const path = rest.join("	");
+    if (!path) continue;
+    stat.set(path, {
       additions: a === "-" ? null : Number(a),
       deletions: d === "-" ? null : Number(d)
     });
@@ -1258,8 +1289,8 @@ async function storeLastSyncRef(cwd, upstreamHash) {
     await git(["update-ref", "refs/cella/last-sync-head", head], cwd);
   }
 }
-async function stagePath(cwd, path4) {
-  await git(["add", "--", path4], cwd, { ignoreErrors: true });
+async function stagePath(cwd, path) {
+  await git(["add", "--", path], cwd, { ignoreErrors: true });
 }
 async function getStoredSyncRef(cwd) {
   const ref = await git(["rev-parse", "refs/cella/last-sync"], cwd, { ignoreErrors: true });
@@ -1272,14 +1303,7 @@ async function getStoredSyncHead(cwd) {
 async function readManifestAtRef(cwd, ref) {
   const raw = await git(["show", `${ref}:${MANIFEST_FILE}`], cwd, { ignoreErrors: true });
   if (!raw) return null;
-  try {
-    const parsed = JSON.parse(raw);
-    const commit = parsed?.upstream?.commit;
-    if (typeof commit !== "string" || !/^[0-9a-f]{40}$/i.test(commit)) return null;
-    return parsed;
-  } catch {
-    return null;
-  }
+  return parseSyncManifest(raw);
 }
 async function readManifestBaseAtRef(cwd, ref) {
   const manifest = await readManifestAtRef(cwd, ref);
@@ -1400,8 +1424,8 @@ async function ensureSyncBase(cwd, headRef, upstreamRef) {
     throw new Error(
       `no common ancestor between the fork and '${upstreamRef}', and no sync base could be determined.
 
-This fork has unrelated history with upstream \u2014 typical for a create-cella scaffold, or after
-upstream squashed its history \u2014 and no recorded or inferable base commit exists after fetching
+This fork has unrelated history with upstream (typical for a create-cella scaffold, or after
+upstream squashed its history) and no recorded or inferable base commit exists after fetching
 upstream. Seed it manually with the upstream commit the fork was created from, then re-run sync:
 
   git update-ref refs/cella/last-sync <upstream-sha>
@@ -1460,9 +1484,15 @@ async function withTemporarySyncBaseGraft(cwd, headRef, baseSha, fn) {
 }
 
 // src/utils/migration-notes.ts
+import { existsSync as existsSync4 } from "fs";
+import { mkdir as mkdir3, readFile as readFile2, rm, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname3, join as join6 } from "path";
 var NOTES_DIR = "cella/migrations";
 var PENDING_FILE = "cella/cella.migrations.json";
 var NOTE_ID = /^\d{8}T\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isCodemodFile(name) {
+  return name.endsWith(".ts") && !name.endsWith(".test.ts");
+}
 function isUpstreamOnly(filePath) {
   return filePath === NOTES_DIR || filePath.startsWith(`${NOTES_DIR}/`);
 }
@@ -1493,7 +1523,7 @@ function parseNote(id, source, fileNames) {
     syncBreaking: meta.get("syncBreaking") === "true",
     clientCacheBump: meta.get("clientCacheBump") === "true",
     roots: (meta.get("roots") ?? "").split(",").map((root) => root.trim()).filter(Boolean),
-    codemod: fileNames.find((name) => name.endsWith(".ts") && !name.endsWith(".test.ts")) ?? null
+    codemod: fileNames.find(isCodemodFile) ?? null
   };
 }
 async function listNoteIds(cwd, ref) {
@@ -1512,23 +1542,23 @@ async function arrivedNoteIds(cwd, from, to) {
   return after.filter((id) => !known.has(id));
 }
 async function readPending(cwd, syncRef) {
-  const path4 = join6(cwd, PENDING_FILE);
-  if (!existsSync4(path4)) return [];
-  const parsed = JSON.parse(await readFile2(path4, "utf8"));
+  const path = join6(cwd, PENDING_FILE);
+  if (!existsSync4(path)) return [];
+  const parsed = JSON.parse(await readFile2(path, "utf8"));
   if (Array.isArray(parsed.pending)) return parsed.pending.filter((id) => typeof id === "string");
   if (!Array.isArray(parsed.applied) || !syncRef) return [];
   const applied = new Set(parsed.applied);
   return (await listNoteIds(cwd, syncRef)).filter((id) => !applied.has(id));
 }
 async function writePending(cwd, ids) {
-  const path4 = join6(cwd, PENDING_FILE);
+  const path = join6(cwd, PENDING_FILE);
   const pending = [...new Set(ids)].sort();
   if (pending.length === 0) {
-    await rm(path4, { force: true });
+    await rm(path, { force: true });
     return;
   }
-  await mkdir3(dirname3(path4), { recursive: true });
-  await writeFile2(path4, `${JSON.stringify({ pending }, null, 2)}
+  await mkdir3(dirname3(path), { recursive: true });
+  await writeFile2(path, `${JSON.stringify({ pending }, null, 2)}
 `, "utf8");
 }
 function noteUrl(upstreamGitHubUrl, commit, id) {
@@ -1572,6 +1602,19 @@ function groupIgnoredUpstreamChanges(files, ignored) {
   for (const group of groups.values()) group.paths.sort();
   return entries.flatMap((entry) => groups.get(entry) ?? []);
 }
+function groupProtectedUpstreamChanges(paths, config) {
+  const entries = [...config.overrides?.pinned ?? [], ...config.overrides?.ignored ?? []].map((entry) => entry.replace(/\/+$/, "")).filter(Boolean);
+  const mostSpecificFirst = [...new Set(entries)].sort((a, b) => b.length - a.length);
+  const groups = /* @__PURE__ */ new Map();
+  for (const path of paths) {
+    const entry = mostSpecificFirst.find((candidate) => isUnderAnyFolder(path, [candidate])) ?? path;
+    const group = groups.get(entry) ?? { entry, paths: [] };
+    group.paths.push(path);
+    groups.set(entry, group);
+  }
+  for (const group of groups.values()) group.paths.sort();
+  return [...groups.values()];
+}
 function isPinnedForSync(filePath, config, unpinned) {
   if (isManagedFile(filePath)) return true;
   if (unpinned) return false;
@@ -1580,7 +1623,7 @@ function isPinnedForSync(filePath, config, unpinned) {
 function hasGlobChars(entry) {
   return entry.includes("*") || entry.includes("?");
 }
-function validateOverrides(config, forkPath) {
+async function validateOverrides(config, forkPath, upstreamRef) {
   const warnings = [];
   const pinned = config.overrides?.pinned || [];
   for (const entry of pinned) {
@@ -1607,6 +1650,7 @@ function validateOverrides(config, forkPath) {
         message: `ignored entry uses glob (not supported, use a path or folder): ${entry}`
       });
     } else if (!existsSync5(join7(forkPath, entry.replace(/\/+$/, "")))) {
+      if (upstreamRef && await fileExistsAtRef(forkPath, upstreamRef, entry.replace(/\/+$/, ""))) continue;
       warnings.push({
         type: "ignored-not-found",
         pattern: entry,
@@ -1623,78 +1667,124 @@ function printWarnings(warnings) {
 }
 
 // src/cli.ts
-function readOptions(opts) {
-  const scope = typeof opts.scope === "string" ? opts.scope : void 0;
+var str = (value) => typeof value === "string" ? value : void 0;
+var flag = (value) => value === true;
+function readOptions(opts, operands = []) {
+  const scope = str(opts.scope);
   if (scope && scope !== "all" && scope !== "risk" && scope !== "protected") {
     throw new Error(`invalid --scope '${scope}'. expected one of: all, risk, protected`);
   }
   const normalizedScope = scope;
+  const run = str(opts.run);
+  if (operands.length > 0 && !run) {
+    throw new Error(`unexpected argument '${operands[0]}'. arguments after the options only go with --run <id>`);
+  }
   return {
-    logFile: opts.log === true,
-    verbose: opts.verbose === true,
-    list: opts.list === true,
-    json: opts.json === true,
-    diff: typeof opts.diff === "string" ? opts.diff : void 0,
-    openDiff: typeof opts.openDiff === "string" ? opts.openDiff : void 0,
+    logFile: flag(opts.log),
+    verbose: flag(opts.verbose),
+    list: flag(opts.list),
+    json: flag(opts.json),
+    diff: str(opts.diff),
+    openDiff: str(opts.openDiff),
     scope: normalizedScope,
-    fork: typeof opts.fork === "string" ? opts.fork : void 0,
-    hard: opts.hard === true,
-    unpinned: opts.unpinned === true,
+    fork: str(opts.fork),
+    hard: flag(opts.hard),
+    unpinned: flag(opts.unpinned),
     track: opts.track === "release" || opts.track === "branch" ? opts.track : void 0,
-    ref: typeof opts.ref === "string" && opts.ref ? opts.ref : void 0,
-    force: opts.force === true,
-    checkOverrides: opts.checkOverrides === true,
-    coverage: opts.coverage === true,
-    all: opts.all === true,
-    show: typeof opts.show === "string" ? opts.show : void 0,
-    extract: typeof opts.extract === "string" ? opts.extract : void 0,
+    ref: str(opts.ref) || void 0,
+    keepConfig: flag(opts.keepConfig),
+    force: flag(opts.force),
+    checkOverrides: flag(opts.checkOverrides),
+    coverage: flag(opts.coverage),
+    since: str(opts.since) || void 0,
+    md: flag(opts.md),
+    all: flag(opts.all),
+    show: str(opts.show),
+    extract: str(opts.extract),
+    run,
+    script: str(opts.script),
+    runArgs: run ? operands : void 0,
     mark: Array.isArray(opts.mark) ? opts.mark.filter((id) => typeof id === "string") : void 0
   };
 }
+var logOption = {
+  flags: "--log",
+  description: "write complete file list to cella-sync.log"
+};
+var jsonOption = {
+  flags: "--json",
+  description: "machine-readable output for tooling/agents"
+};
+var trackOption = {
+  flags: "--track <mode>",
+  description: "override upstream tracking for this run: release|branch"
+};
+var refOption = {
+  flags: "--ref <ref>",
+  description: "pin the upstream commit for this run: sha, release tag or branch"
+};
+var hardOption = {
+  flags: "--hard",
+  description: "overwrite drifted files with upstream version (aggressive realignment)"
+};
+var verboseOption = {
+  flags: "-V, --verbose",
+  description: "show detailed output during operations"
+};
+var forkOption = {
+  flags: "--fork <name>",
+  description: "pre-select a fork by name (skips the fork selection prompt)"
+};
 var serviceDefinitions = [
   {
     name: "analyze",
     description: "dry run to see what would change on sync",
     options: [
-      { flags: "--log", description: "write complete file list to cella-sync.log" },
+      logOption,
       { flags: "--list", description: "non-interactive output for tooling (one file per line)" },
-      { flags: "--json", description: "machine-readable output for tooling/agents" },
+      jsonOption,
       { flags: "--scope <scope>", description: "analyze scope for --list/--json: all|risk|protected" },
-      { flags: "--track <mode>", description: "override upstream tracking for this run: release|branch" },
-      { flags: "--ref <ref>", description: "pin the upstream commit for this run: sha, release tag or branch" },
-      { flags: "--diff <path>", description: "print unified diff for one file, then exit" },
+      trackOption,
+      refOption,
+      { flags: "--diff <path>", description: "print the unified diff for one file, then exit" },
       { flags: "--open-diff <path>", description: "open a browser diff for one file, then exit" }
     ],
     includeInMenu: (context) => !context.isUpstreamRepo
   },
   {
     name: "sync",
-    description: "merge upstream changes into your app",
+    description: "merge upstream changes onto a fresh branch, sync package.json and open a squash-merge PR",
     options: [
-      { flags: "--log", description: "write complete file list to cella-sync.log" },
-      { flags: "--hard", description: "overwrite drifted files with upstream version (aggressive realignment)" },
+      logOption,
+      hardOption,
       { flags: "--unpinned", description: "ignore pinned files (except package.json) to resurface upstream changes" },
-      { flags: "--track <mode>", description: "override upstream tracking for this run: release|branch" },
-      { flags: "--ref <ref>", description: "pin the upstream commit for this run: sha, release tag or branch" }
+      trackOption,
+      refOption,
+      { flags: "--keep-config", description: "merge with your sync config as it stands when upstream changed its own" }
     ],
-    includeInMenu: (context) => !context.isUpstreamRepo,
-    menuDescription: () => "merge upstream changes + sync package.json"
+    includeInMenu: (context) => !context.isUpstreamRepo
   },
   {
     name: "migrate",
     description: "list the upstream migration notes this app has not handled yet",
     options: [
       { flags: "--all", description: "list every upstream note, handled or not" },
-      { flags: "--json", description: "machine-readable output for tooling/agents" },
+      jsonOption,
       { flags: "--show <id>", description: "print one note's README" },
       { flags: "--extract <id>", description: "write one note's folder under node_modules/.cache to run its codemod" },
+      { flags: "--run <id>", description: "run one note's codemod; files identical to upstream stay as they are" },
+      { flags: "--script <file>", description: "with --run: the script to run when the note folder holds several" },
       { flags: "--mark <ids...>", description: "record notes as handled" }
     ],
+    operands: {
+      flags: "[codemodArgs...]",
+      description: "with --run, after `--`: arguments for the codemod (default: inventory and the note's roots)"
+    },
     includeInMenu: (context) => !context.isUpstreamRepo
   },
   {
     name: "audit",
-    description: "check for outdated packages & vulnerabilities",
+    description: "check for outdated packages and vulnerabilities",
     options: [
       { flags: "--list", description: "skip interactive update prompts after printing audit results" },
       { flags: "--force", description: "bypass pnpm metadata cache for fresh registry data" },
@@ -1703,23 +1793,27 @@ var serviceDefinitions = [
   },
   {
     name: "forks",
-    description: "sync downstream to local fork repositories",
+    description: "run normal sync inside local fork repositories",
     options: [
-      { flags: "--fork <name>", description: "pre-select fork by name (skips fork selection prompt)" },
+      forkOption,
       { flags: "--log", description: "write complete file list to cella-sync.log for each synced fork" },
-      { flags: "-V, --verbose", description: "show detailed output during operations" },
-      { flags: "--hard", description: "overwrite drifted files with upstream version (aggressive realignment)" }
+      verboseOption,
+      hardOption,
+      {
+        flags: "--keep-config",
+        description: "merge with the fork's sync config as it stands when upstream changed its own"
+      }
     ],
     includeInMenu: (context) => context.hasForks
   },
   {
     name: "contributions",
-    description: "pull and adopt changes from forks",
+    description: "pull and adopt changes from local forks",
     options: [
-      { flags: "--fork <name>", description: "select a specific fork directly (skips fork selection)" },
-      { flags: "--list", description: "non-interactive output (one file per line)" },
-      { flags: "--json", description: "machine-readable JSON output for tooling/agents" },
-      { flags: "--diff <path>", description: "print the unified diff for a single contributed file, then exit" }
+      forkOption,
+      { flags: "--list", description: "non-interactive output for tooling (tab-separated rows)" },
+      jsonOption,
+      { flags: "--diff <path>", description: "print the unified diff for one contributed file, then exit" }
     ],
     includeInMenu: (context) => context.hasForks
   },
@@ -1727,26 +1821,31 @@ var serviceDefinitions = [
     name: "stats",
     description: "count files by category and workspace package",
     options: [
-      { flags: "-V, --verbose", description: "show detailed output during operations" },
-      { flags: "--coverage", description: "regenerate test coverage before showing the stats summary" }
+      verboseOption,
+      { flags: "--coverage", description: "regenerate test coverage before showing the stats summary" },
+      {
+        flags: "--since <ref>",
+        description: "count what the current branch changed since it left <ref>, by kind of file"
+      },
+      { flags: "--md", description: "with --since: print the table as markdown for a pull request description" }
     ]
   }
 ];
-async function getMenuContext(userConfig, forkPath) {
+function getMenuContext(userConfig, forkPath) {
   return {
     hasForks: (userConfig.forks?.length ?? 0) > 0,
-    isUpstreamRepo: JSON.parse(readFileSync(join8(forkPath, "package.json"), "utf8")).name === "cella"
+    isUpstreamRepo: isUpstreamRepo(forkPath)
   };
 }
 function buildServiceChoices(context) {
   const label = (name) => name.padEnd(14);
   const baseChoices = serviceDefinitions.filter((service) => service.includeInMenu?.(context) ?? true).map((service) => ({
     value: service.name,
-    name: `${label(service.name)}${colors_default.dim(service.menuDescription?.(context) ?? service.description)}`
+    name: `${label(service.name)}${colors_default.dim(service.description)}`
   }));
   return [
     ...baseChoices,
-    { type: "separator", separator: "\u2500".repeat(40) },
+    { type: "separator", separator: MENU_DIVIDER },
     { value: "exit", name: colors_default.red(`${label("exit")}${colors_default.dim("quit without doing anything")}`) }
   ];
 }
@@ -1755,10 +1854,13 @@ function addServiceCommand(program, definition, setSelection) {
   for (const option of definition.options ?? []) {
     command.option(option.flags, option.description);
   }
-  command.action((opts) => {
+  if (definition.operands) command.argument(definition.operands.flags, definition.operands.description);
+  command.action((...args) => {
+    const operands = definition.operands ? args[0] : [];
+    const opts = definition.operands ? args[1] : args[0];
     setSelection({
       service: definition.name,
-      options: readOptions(opts)
+      options: readOptions(opts, operands)
     });
   });
 }
@@ -1775,8 +1877,10 @@ function buildProgram(setSelection) {
       "  $ cella sync --unpinned",
       "  $ cella sync --track branch",
       "  $ cella sync --ref 4f7d87c",
+      "  $ cella migrate --run 20261001T2116-tailwind-class-conventions -- rewrite frontend/src",
       "  $ cella migrate --mark 20261002T0614-config-switch",
       "  $ cella audit --check-overrides",
+      "  $ cella stats --since origin/main --md",
       "  $ cella contributions --fork raak --json"
     ].join("\n")
   );
@@ -1799,7 +1903,7 @@ function parseCommandLine(argv) {
 async function promptForService(userConfig, forkPath) {
   const selected = await select({
     message: "choose a service:",
-    choices: buildServiceChoices(await getMenuContext(userConfig, forkPath)),
+    choices: buildServiceChoices(getMenuContext(userConfig, forkPath)),
     loop: false
   });
   if (selected === "exit") {
@@ -1822,9 +1926,10 @@ function buildRuntimeConfig(userConfig, forkPath, selection) {
 }
 async function parseCli(userConfig, forkPath) {
   const selection = parseCommandLine(process5.argv);
-  if (selection.options.json || selection.options.diff) setJsonMode(true);
+  const machineList = selection.options.list && selection.service !== "audit";
+  if (selection.options.json || selection.options.diff || selection.options.md || machineList) setJsonMode(true);
   printHeader();
-  const warnings = validateOverrides(userConfig, forkPath);
+  const warnings = await validateOverrides(userConfig, forkPath, resolveUpstream(userConfig.settings).branchRef);
   if (warnings.length > 0) {
     printWarnings(warnings);
     console.info();
@@ -1842,14 +1947,14 @@ import { basename as basename4 } from "path";
 import { execFileSync } from "child_process";
 import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename2, join as join9 } from "path";
+import { basename as basename2, join as join8 } from "path";
 import process6 from "process";
 function gitDiffFile(cwd, range, filePath, options = {}) {
   const args = ["diff", "--no-color"];
   if (options.dstPrefix) args.push("--src-prefix=cella/", `--dst-prefix=${options.dstPrefix}/`);
   args.push(range, "--", filePath);
   try {
-    return execFileSync("git", args, { cwd, maxBuffer: 50 * 1024 * 1024 });
+    return execFileSync("git", args, { cwd, maxBuffer: MAX_BUFFER });
   } catch (error) {
     const stderr = error.stderr?.toString().trim();
     throw new Error(stderr || `failed to diff ${filePath}`);
@@ -1936,9 +2041,9 @@ function openWithDefaultApp(target) {
 }
 async function openDiffInBrowser(patch, meta, repoPath) {
   const html = await renderDiffPage(patch, meta);
-  const dir = join9(tmpdir(), `cella-diff-${basename2(repoPath)}`);
+  const dir = join8(tmpdir(), `cella-diff-${basename2(repoPath)}`);
   mkdirSync(dir, { recursive: true });
-  const outPath = join9(dir, `${meta.filePath.replace(/[^\w.-]+/g, "-")}.html`);
+  const outPath = join8(dir, `${meta.filePath.replace(/[^\w.-]+/g, "-")}.html`);
   writeFileSync2(outPath, html);
   openWithDefaultApp(outPath);
   return outPath;
@@ -1947,13 +2052,13 @@ async function openDiffInBrowser(patch, meta, repoPath) {
 // src/services/merge-engine.ts
 import { existsSync as existsSync7 } from "fs";
 import { rm as rm2 } from "fs/promises";
-import { join as join11 } from "path";
+import { join as join10 } from "path";
 
 // src/utils/cleanup.ts
 import { createHash } from "crypto";
 import { existsSync as existsSync6, rmSync } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename3, join as join10, resolve as resolve4 } from "path";
+import { basename as basename3, join as join9, resolve as resolve4 } from "path";
 import process7 from "process";
 var WORKTREE_PREFIXES = {
   sync: "cella-sync-",
@@ -1961,10 +2066,10 @@ var WORKTREE_PREFIXES = {
 };
 function buildWorktreePath(kind, repoPath) {
   const key = createHash("sha256").update(resolve4(repoPath)).digest("hex").slice(0, 8);
-  return join10(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}-${key}`);
+  return join9(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}-${key}`);
 }
 function legacyWorktreePath(kind, repoPath) {
-  return join10(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}`);
+  return join9(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}`);
 }
 function getWorktreePath(repoPath) {
   return buildWorktreePath("sync", repoPath);
@@ -2003,7 +2108,7 @@ async function cleanupLeftoverWorktrees(repoPath) {
 }
 async function handleAbort(signal) {
   console.info();
-  console.info(`${warningMark} Interrupted (${signal}) - cleaning up...`);
+  console.info(`${warningMark} interrupted (${signal}): cleaning up...`);
   if (currentRepoPath && currentWorktreePath) {
     try {
       await mergeAbort(currentWorktreePath);
@@ -2011,11 +2116,9 @@ async function handleAbort(signal) {
     }
     try {
       await cleanupWorktree(currentRepoPath, currentWorktreePath);
-      console.info(`${colors_default.green("\u2713")} no changes were made to your repository.`);
+      console.info(`${checkMark} no changes were made to your repository.`);
     } catch (error) {
-      console.error(
-        `${colors_default.red("\u2717")} failed to clean up worktree: ${error instanceof Error ? error.message : "unknown error"}`
-      );
+      console.error(`${colors_default.red("\u2717")} failed to clean up worktree: ${errorMessage(error)}`);
     }
   }
   process7.exit(1);
@@ -2111,25 +2214,44 @@ function readProperty(object, name, sourceFile) {
   }
   return void 0;
 }
+function readStringEntries(node) {
+  if (!Node.isArrayLiteralExpression(node)) return null;
+  const entries = [];
+  for (const element of node.getElements()) {
+    if (Node.isStringLiteral(element) || Node.isNoSubstitutionTemplateLiteral(element)) {
+      entries.push(element.getLiteralValue());
+    }
+  }
+  return entries;
+}
+function readPackageJsonSync(config, sourceFile) {
+  const settings = readProperty(config, "settings", sourceFile);
+  if (settings === void 0) return [...DEFAULT_PACKAGE_JSON_SYNC];
+  if (!settings || !Node.isObjectLiteralExpression(settings)) return null;
+  const keys = readProperty(settings, "packageJsonSync", sourceFile);
+  if (keys === void 0) return [...DEFAULT_PACKAGE_JSON_SYNC];
+  return keys ? readStringEntries(keys) : null;
+}
 function parseOverrideLists(source) {
   try {
     const project = new Project2({ useInMemoryFileSystem: true, skipLoadingLibFiles: true });
     const sourceFile = project.createSourceFile("cella.config.ts", source);
     const config = findConfigObject(sourceFile);
     if (!config) return null;
+    const lists = {
+      pinned: [],
+      ignored: [],
+      packageJsonSync: readPackageJsonSync(config, sourceFile)
+    };
     const overrides = readProperty(config, "overrides", sourceFile);
-    if (overrides === void 0) return { pinned: [], ignored: [] };
+    if (overrides === void 0) return lists;
     if (!overrides || !Node.isObjectLiteralExpression(overrides)) return null;
-    const lists = { pinned: [], ignored: [] };
     for (const key of LIST_KEYS) {
       const list = readProperty(overrides, key, sourceFile);
       if (list === void 0) continue;
-      if (!list || !Node.isArrayLiteralExpression(list)) return null;
-      for (const element of list.getElements()) {
-        if (Node.isStringLiteral(element) || Node.isNoSubstitutionTemplateLiteral(element)) {
-          lists[key].push(element.getLiteralValue());
-        }
-      }
+      const entries = list ? readStringEntries(list) : null;
+      if (!entries) return null;
+      lists[key] = entries;
     }
     return lists;
   } catch {
@@ -2149,11 +2271,19 @@ function diffOverrideLists(base, incoming, fork) {
       removed: [...baseSet].filter((entry) => !incomingSet.has(entry) && forkEntries.includes(entry))
     };
   };
-  return { pinned: diff("pinned"), ignored: diff("ignored") };
+  const diffKeys = () => {
+    const [baseKeys, incomingKeys, forkKeys] = [base.packageJsonSync, incoming.packageJsonSync, fork.packageJsonSync];
+    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() };
 }
 async function readConfigSourceAtRef(repoPath, ref) {
-  for (const path4 of CONFIG_FILE_PATHS) {
-    const source = await git(["show", `${ref}:${path4}`], repoPath, { ignoreErrors: true });
+  for (const path of CONFIG_FILE_PATHS) {
+    const source = await git(["show", `${ref}:${path}`], repoPath, { ignoreErrors: true });
     if (source) return source;
   }
   return null;
@@ -2170,10 +2300,11 @@ async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, for
   if (!incoming) return { kind: "unreadable", side: "incoming" };
   const fork = {
     pinned: forkConfig.overrides?.pinned ?? [],
-    ignored: forkConfig.overrides?.ignored ?? []
+    ignored: forkConfig.overrides?.ignored ?? [],
+    packageJsonSync: forkConfig.settings.packageJsonSync ?? DEFAULT_PACKAGE_JSON_SYNC
   };
   const changes = diffOverrideLists(base, incoming, fork);
-  const count = LIST_KEYS.reduce((n, key) => n + changes[key].added.length + changes[key].removed.length, 0);
+  const count = Object.values(changes).reduce((n, list) => n + list.added.length + list.removed.length, 0);
   return count > 0 ? { kind: "changes", ...changes } : void 0;
 }
 
@@ -2297,10 +2428,8 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
         status = fileIsPinned ? "pinned" : "diverged";
       } else if (forkChanged && !upstreamChanged2) {
         status = fileIsPinned ? "ahead" : predicates.hard ? "behind" : "drifted";
-      } else if (!forkChanged && upstreamChanged2) {
-        status = "behind";
       } else {
-        status = "identical";
+        status = "behind";
       }
     }
     const upstreamChanged = (fileIsPinned || fileIsIgnored) && inUpstream && upstreamHash !== baseHash && forkHash !== baseHash;
@@ -2385,6 +2514,21 @@ async function enrichChangeInfo(repoPath, files, mergeBaseRef, localRef, incomin
 }
 
 // src/services/merge-engine.ts
+var BehindSyncPointError = class extends Error {
+};
+var UpstreamConfigChangedError = class extends Error {
+  report;
+  constructor(report) {
+    super(
+      [
+        "upstream changed its sync 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")
+    );
+    this.report = report;
+  }
+};
 function getGitHubBaseUrl(remoteUrl) {
   const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/([^.]+)(?:\.git)?$/);
   if (sshMatch) {
@@ -2396,10 +2540,13 @@ function getGitHubBaseUrl(remoteUrl) {
   }
   return null;
 }
+function isProtectedFile(file) {
+  return file.isIgnored || file.isPinned;
+}
 function syncPredicates(config) {
   return {
-    isIgnored: (path4) => isIgnored(path4, config),
-    isPinned: (path4) => isPinnedForSync(path4, config, config.unpinned),
+    isIgnored: (path) => isIgnored(path, config),
+    isPinned: (path) => isPinnedForSync(path, config, config.unpinned),
     hard: config.hard
   };
 }
@@ -2418,6 +2565,7 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
   for (const file of analyzedFiles) {
     const { path: filePath, status, isPinned: pinned, isIgnored: ignored, existsInFork } = file;
     if (status === "identical" || status === "ahead") continue;
+    if (!isProtectedFile(file)) continue;
     if (ignored && existsInFork) {
       batchRestorePaths.push(filePath);
     } else if (ignored && !existsInFork) {
@@ -2429,12 +2577,7 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
     }
   }
   onProgress?.("starting merge in fork...");
-  await withTemporarySyncBaseGraft(
-    forkPath,
-    "HEAD",
-    mergeBaseRef,
-    () => merge(forkPath, upstreamRef, { noCommit: true, noEdit: true })
-  );
+  await withTemporarySyncBaseGraft(forkPath, "HEAD", mergeBaseRef, () => merge(forkPath, upstreamRef));
   if (batchRestorePaths.length > 0) {
     onProgress?.(`batch restoring ${batchRestorePaths.length} pinned/ignored files...`);
     await batchRestoreToHead(forkPath, batchRestorePaths);
@@ -2447,29 +2590,11 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
     }
   }
   for (const file of analyzedFiles) {
-    const { path: filePath, status, isPinned: pinned, isIgnored: ignored, existsInFork } = file;
+    const { path: filePath, status, existsInFork } = file;
     if (status === "identical" || status === "ahead") {
       continue;
     }
-    if (ignored) continue;
-    if (pinned && !file.renamedFrom) continue;
-    if (pinned && file.renamedFrom) {
-      const oldPathExists = await fileExistsInWorktree(forkPath, file.renamedFrom);
-      if (oldPathExists) {
-        onProgress?.(`\u2192 ${file.renamedFrom} \u2192 ${filePath}: moving fork content (pinned rename)`);
-        try {
-          await gitMv(forkPath, file.renamedFrom, filePath);
-        } catch {
-          await removeFileFully(forkPath, file.renamedFrom);
-          await checkoutFromRef(forkPath, "HEAD", file.renamedFrom).catch(() => {
-          });
-        }
-      } else {
-        onProgress?.(`\u2192 ${filePath}: keeping fork content (pinned rename, old path removed)`);
-        await restoreToHead(forkPath, filePath);
-      }
-      continue;
-    }
+    if (isProtectedFile(file)) continue;
     if (status === "diverged") {
       onProgress?.(`\u2192 ${filePath}: using git merge result (diverged)`);
       continue;
@@ -2514,6 +2639,7 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
     }
   }
   const protectedConflicts = analyzedFiles.filter((file) => file.upstreamChanged).map((file) => file.path);
+  const protectedConflictSet = new Set(protectedConflicts);
   const gitConflicts = await getConflictedFiles(forkPath);
   for (const filePath of gitConflicts) {
     const isProtected = isIgnored(filePath, config) || isPinnedForSync(filePath, config, config.unpinned);
@@ -2521,7 +2647,10 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
     if (await fileExistsAtRef(forkPath, "HEAD", filePath)) {
       onProgress?.(`\u2192 ${filePath}: keeping fork (protected conflict)`);
       await restoreToHead(forkPath, filePath);
-      if (!protectedConflicts.includes(filePath)) protectedConflicts.push(filePath);
+      if (!protectedConflictSet.has(filePath)) {
+        protectedConflictSet.add(filePath);
+        protectedConflicts.push(filePath);
+      }
     } else {
       onProgress?.(`\u2192 ${filePath}: removing (protected conflict, not in fork)`);
       await removeFileFully(forkPath, filePath);
@@ -2553,8 +2682,7 @@ function calculateSummary(files) {
     pinned: 0,
     ignored: 0,
     deleted: 0,
-    renamed: 0,
-    total: files.length
+    renamed: 0
   };
   for (const file of files) {
     if (file.status !== "identical" && isManagedFile(file.path)) {
@@ -2574,12 +2702,12 @@ async function resolvePinnedRef(forkPath, config, remoteName, branchRef, ref) {
   const resolved = await resolveUpstreamCommit(forkPath, remoteName, ref);
   if (!resolved) {
     throw new Error(
-      `--ref '${ref}' does not resolve to a commit. Pass a commit sha, a release tag (v*) or a branch on ${config.settings.upstreamUrl}.`
+      `--ref '${ref}' does not resolve to a commit. Pass a commit sha, a release tag or a branch on ${config.settings.upstreamUrl}.`
     );
   }
   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 (v*). Sync only to commits upstream has published there.`
+      `--ref '${ref}' (${resolved.sha.slice(0, 7)}) is not on ${branchRef} or in an upstream release. Sync only to commits upstream has published there.`
     );
   }
   return resolved.release ? { ref: resolved.release.ref, releaseTag: resolved.release.tag } : { ref: resolved.sha };
@@ -2600,7 +2728,7 @@ async function prepareUpstream(config, onProgress, onStep) {
   const track = config.track ?? configTrack;
   await ensureRemote(forkPath, remoteName, config.settings.upstreamUrl);
   onProgress?.(`fetching upstream (${remoteName})...`);
-  await fetch2(forkPath, remoteName);
+  await fetchRemote(forkPath, remoteName);
   let upstreamRef = branchRef;
   let releaseTag;
   if (config.ref) {
@@ -2613,7 +2741,7 @@ async function prepareUpstream(config, onProgress, onStep) {
     const latest = await resolveLatestReleaseTag(forkPath, remoteName);
     if (!latest) {
       throw new Error(
-        `no upstream releases (v*) found on '${remoteName}'. Set upstreamTrack: 'branch' to follow ${branchRef}, or check that ${config.settings.upstreamUrl} publishes release tags.`
+        `no upstream release tags found on '${remoteName}'. Set upstreamTrack: 'branch' to follow ${branchRef}, or check that ${config.settings.upstreamUrl} publishes release tags.`
       );
     }
     upstreamRef = latest.ref;
@@ -2638,21 +2766,23 @@ async function prepareUpstream(config, onProgress, onStep) {
       getShortSha(forkPath, syncPoint)
     ]);
     const hint = 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}.`;
-    throw new Error(
+    throw new BehindSyncPointError(
       `upstream ${upstreamLabel} (${upstreamShort}) is behind the last sync point ${syncShort}: the fork already has it, and syncing it would revert the upstream changes after it.
 ${hint}`
     );
   }
   const commitCount = await countCommitsBetween(forkPath, mergeBase, upstreamRef);
-  const commitListMax = 50;
-  const commitSkip = commitCount > commitListMax ? commitCount - commitListMax : 0;
-  const upstreamCommits = commitCount > 0 ? await listCommitsBetween(forkPath, mergeBase, upstreamRef, {
-    oldestFirst: true,
-    skip: commitSkip,
-    limit: commitListMax
-  }) : [];
+  const commitSkip = commitCount > COMMIT_LIST_MAX ? commitCount - COMMIT_LIST_MAX : 0;
+  const upstreamCommits = commitCount > 0 ? await listCommitsBetween(forkPath, mergeBase, upstreamRef, { skip: commitSkip, limit: COMMIT_LIST_MAX }) : [];
   onStep?.("fetched upstream", formatFetchedUpstreamDetail(commitCount, upstreamCommits, upstreamGitHubUrl));
-  return { upstreamRef, releaseTag, mergeBase, upstreamGitHubUrl, upstreamCommit, upstreamCommits };
+  return { upstreamRef, releaseTag, mergeBase, syncPoint, upstreamGitHubUrl, upstreamCommit, upstreamCommits };
+}
+async function assertSyncConfigFollowed(config, ctx) {
+  if (config.keepConfig) return;
+  const report = await compareUpstreamOverrides(config.forkPath, ctx.syncPoint, ctx.upstreamRef, config).catch(
+    () => void 0
+  );
+  if (report?.kind === "changes") throw new UpstreamConfigChangedError(report);
 }
 function resultMeta(config, ctx) {
   return {
@@ -2664,7 +2794,7 @@ function resultMeta(config, ctx) {
     upstreamCommits: ctx.upstreamCommits
   };
 }
-async function upstreamOnlyReports(config, ctx, files) {
+async function upstreamOnlyReports(config, ctx, files, protectedConflicts) {
   const { forkPath } = config;
   try {
     const [baseSha, upstreamSha, upstreamOverrides] = await Promise.all([
@@ -2676,7 +2806,8 @@ async function upstreamOnlyReports(config, ctx, files) {
     return {
       upstreamDiffRange: `${baseSha}..${upstreamSha}`,
       upstreamOverrides,
-      ignoredUpstreamChanges: groupIgnoredUpstreamChanges(files, config.overrides?.ignored ?? [])
+      ignoredUpstreamChanges: groupIgnoredUpstreamChanges(files, config.overrides?.ignored ?? []),
+      protectedUpstreamChanges: groupProtectedUpstreamChanges(protectedConflicts, config)
     };
   } catch {
     return {};
@@ -2685,12 +2816,10 @@ async function upstreamOnlyReports(config, ctx, files) {
 async function readNotesInRange(config, ctx) {
   const { forkPath } = config;
   try {
-    const aggressive = config.hard === true || config.unpinned === true;
-    const syncBase = aggressive ? (await getEffectiveMergeBase(forkPath, "HEAD", ctx.upstreamRef)).base : ctx.mergeBase;
     const [total, arrived, pending] = await Promise.all([
       listNoteIds(forkPath, ctx.upstreamRef),
-      arrivedNoteIds(forkPath, syncBase, ctx.upstreamRef),
-      readPending(forkPath, syncBase)
+      arrivedNoteIds(forkPath, ctx.syncPoint, ctx.upstreamRef),
+      readPending(forkPath, ctx.syncPoint)
     ]);
     return { total: total.length, arrived, pending: [.../* @__PURE__ */ new Set([...pending, ...arrived])] };
   } catch {
@@ -2701,14 +2830,15 @@ function notesResult(notes) {
   return notes ? { migrationNotes: { total: notes.total, arrived: notes.arrived, open: notes.pending.length } } : {};
 }
 async function removeUpstreamOnlyCopy(forkPath, onStep) {
-  if (!existsSync7(join11(forkPath, NOTES_DIR))) return;
+  if (!existsSync7(join10(forkPath, NOTES_DIR))) return;
   await git(["rm", "-r", "-q", "--ignore-unmatch", "--", NOTES_DIR], forkPath);
-  await rm2(join11(forkPath, NOTES_DIR), { recursive: true, force: true });
+  await rm2(join10(forkPath, NOTES_DIR), { recursive: true, force: true });
   onStep?.("migration notes", `removed ${NOTES_DIR}/: notes stay upstream, list them with pnpm cella migrate`);
 }
 async function runSyncMerge(config, ctx, onProgress, onStep) {
   const { forkPath } = config;
   const { upstreamRef, releaseTag, mergeBase, upstreamGitHubUrl, upstreamCommit } = ctx;
+  await assertSyncConfigFollowed(config, ctx);
   const notes = await readNotesInRange(config, ctx);
   const { remainingConflicts, analyzedFiles, autoMergedFiles, protectedConflicts } = await applyDirectMerge(
     forkPath,
@@ -2719,9 +2849,7 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
   );
   const summary = calculateSummary(analyzedFiles);
   const synced = analyzedFiles.filter((file) => ["behind", "diverged", "renamed"].includes(file.status)).length;
-  const totalResolved = analyzedFiles.filter(
-    (file) => ["behind", "diverged", "renamed", "ignored", "pinned"].includes(file.status)
-  ).length;
+  const totalResolved = analyzedFiles.filter((file) => SYNC_APPLIED_STATUSES.includes(file.status)).length;
   const syncManifest = {
     upstream: {
       repo: upstreamGitHubUrl ? upstreamGitHubUrl.replace("https://github.com/", "") : void 0,
@@ -2764,7 +2892,7 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
     autoMergedFiles,
     protectedConflicts,
     ...resultMeta(config, ctx),
-    ...await upstreamOnlyReports(config, ctx, analyzedFiles),
+    ...await upstreamOnlyReports(config, ctx, analyzedFiles, protectedConflicts),
     ...notesResult(notes)
   };
 }
@@ -2776,12 +2904,7 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
   await createWorktree(forkPath, worktreePath, "HEAD");
   onStep?.("worktree created", worktreePath);
   onProgress?.("performing merge in worktree...");
-  await withTemporarySyncBaseGraft(
-    worktreePath,
-    "HEAD",
-    ctx.mergeBase,
-    () => merge(worktreePath, ctx.upstreamRef, { noCommit: true, noEdit: true })
-  );
+  await withTemporarySyncBaseGraft(worktreePath, "HEAD", ctx.mergeBase, () => merge(worktreePath, ctx.upstreamRef));
   onStep?.("merge complete", "upstream merged into worktree");
   onProgress?.("analyzing files...");
   const analyzedFiles = await analyzeRefs(
@@ -2793,8 +2916,9 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
     onProgress
   );
   await enrichChangeInfo(forkPath, analyzedFiles, ctx.mergeBase, "HEAD", ctx.upstreamRef);
-  const reports = await upstreamOnlyReports(config, ctx, analyzedFiles);
-  onStep?.("analysis complete", `${analyzedFiles.length} files analyzed, dry run \u2014 no changes applied`);
+  const protectedConflicts = analyzedFiles.filter((f) => f.upstreamChanged).map((f) => f.path);
+  const reports = await upstreamOnlyReports(config, ctx, analyzedFiles, protectedConflicts);
+  onStep?.("analysis complete", `${analyzedFiles.length} files analyzed, dry run, no changes applied`);
   onProgress?.("cleaning up worktree...");
   await cleanupWorktree(forkPath, worktreePath);
   return {
@@ -2803,7 +2927,7 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
     summary: calculateSummary(analyzedFiles),
     // For analyze mode, count diverged files as potential conflicts
     conflicts: analyzedFiles.filter((f) => f.status === "diverged").map((f) => f.path),
-    protectedConflicts: analyzedFiles.filter((f) => f.upstreamChanged).map((f) => f.path),
+    protectedConflicts,
     ...resultMeta(config, ctx),
     ...reports,
     ...notesResult(notes)
@@ -2823,23 +2947,39 @@ async function runMergeEngine(config, options) {
     throw error;
   }
 }
+async function runEngineWithSpinner(config, apply) {
+  return runMergeEngine(config, {
+    apply,
+    onProgress: (message) => {
+      spinnerText(message);
+    },
+    onStep: (label, detail) => {
+      spinnerSuccess(label, detail);
+      createSpinner("...");
+    }
+  });
+}
 
 // src/services/migrate.ts
-import { execFileSync as execFileSync2 } from "child_process";
+import { execFileSync as execFileSync2, spawnSync } from "child_process";
 import { mkdir as mkdir4, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname4, join as join12 } from "path";
+import { dirname as dirname4, join as join11 } from "path";
 var EXTRACT_DIR = "node_modules/.cache/cella/migrations";
+var RESTORED_LIST_MAX = 20;
+async function ensureUpstreamCommit(config, sha) {
+  const { forkPath } = config;
+  const present = async () => !!await git(["rev-parse", "--verify", "--quiet", `${sha}^{commit}`], forkPath, { ignoreErrors: true });
+  if (await present()) return;
+  await ensureRemote(forkPath, DEFAULT_UPSTREAM_REMOTE, config.settings.upstreamUrl);
+  await fetchRemote(forkPath, DEFAULT_UPSTREAM_REMOTE);
+  if (!await present())
+    throw new Error(`upstream commit ${sha.slice(0, 7)} is not reachable from '${DEFAULT_UPSTREAM_REMOTE}'`);
+}
 async function resolveNotesRef(config) {
   const { forkPath } = config;
   const ref = await getStoredSyncRef(forkPath) ?? await readManifestBaseAtRef(forkPath, "HEAD");
   if (!ref) return null;
-  const present = async () => !!await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], forkPath, { ignoreErrors: true });
-  if (!await present()) {
-    await ensureRemote(forkPath, DEFAULT_UPSTREAM_REMOTE, config.settings.upstreamUrl);
-    await fetch2(forkPath, DEFAULT_UPSTREAM_REMOTE);
-    if (!await present())
-      throw new Error(`upstream commit ${ref.slice(0, 7)} is not reachable from '${DEFAULT_UPSTREAM_REMOTE}'`);
-  }
+  await ensureUpstreamCommit(config, ref);
   return ref;
 }
 async function readNotesStatus(config) {
@@ -2881,27 +3021,88 @@ function printNote(index, note, url) {
   if (note.summary) console.info(`   ${note.summary}`);
   console.info(colors_default.dim(`   read:    pnpm cella migrate --show ${note.id}`));
   if (url) console.info(colors_default.dim(`            ${url}`));
-  if (note.codemod) console.info(colors_default.dim(`   codemod: pnpm cella migrate --extract ${note.id}`));
+  if (note.codemod) console.info(colors_default.dim(`   codemod: pnpm cella migrate --run ${note.id}`));
   console.info();
 }
-async function extractNote(config, ref, id) {
+async function writeNoteFolder(config, ref, id) {
   const { forkPath } = config;
   const note = await readNote(forkPath, ref, id);
   if (!note) throw new Error(`no migration note '${id}' at upstream ${ref.slice(0, 7)}`);
   const files = (await git(["ls-tree", "-r", "--name-only", `${ref}:${NOTES_DIR}/${id}`], forkPath)).split("\n").filter(Boolean);
-  const target = join12(EXTRACT_DIR, id);
+  const target = join11(EXTRACT_DIR, id);
   for (const file of files) {
     const content = execFileSync2("git", ["show", `${ref}:${NOTES_DIR}/${id}/${file}`], {
       cwd: forkPath,
-      maxBuffer: 50 * 1024 * 1024
+      maxBuffer: MAX_BUFFER
     });
-    const path4 = join12(forkPath, target, file);
-    await mkdir4(dirname4(path4), { recursive: true });
-    await writeFile3(path4, content);
+    const path = join11(forkPath, target, file);
+    await mkdir4(dirname4(path), { recursive: true });
+    await writeFile3(path, content);
   }
-  console.info(`${colors_default.green("\u2713")} extracted ${files.length} file(s) to ${target}/`);
+  return { note, target, files };
+}
+async function extractNote(config, ref, id) {
+  const { note, target, files } = await writeNoteFolder(config, ref, id);
+  console.info(`${checkMark} extracted ${files.length} file(s) to ${target}/`);
   console.info(colors_default.dim(`  the README's ${NOTES_DIR}/${id}/ paths are this folder.`));
-  if (note.codemod) console.info(colors_default.dim(`  pnpm exec tsx ${target}/${note.codemod} inventory ${note.roots.join(" ")}`));
+  if (note.codemod) {
+    console.info(colors_default.dim(`  pnpm exec tsx ${target}/${note.codemod} inventory ${note.roots.join(" ")}`));
+    console.info(colors_default.dim(`  or, keeping files identical to upstream as they are: pnpm cella migrate --run ${id}`));
+  }
+}
+function resolveCodemod(id, files, script) {
+  if (script) {
+    const name = script.replace(/^\.\//, "");
+    if (!files.includes(name)) {
+      throw new Error(`migration note '${id}' has no file '${script}'. its files: ${files.join(", ")}`);
+    }
+    return name;
+  }
+  const scripts = files.filter((file) => !file.includes("/") && isCodemodFile(file));
+  if (scripts.length === 0) {
+    throw new Error(
+      `migration note '${id}' ships no codemod script: its steps are manual, read them with \`pnpm cella migrate --show ${id}\`.`
+    );
+  }
+  if (scripts.length > 1) {
+    throw new Error(
+      `migration note '${id}' ships ${scripts.length} scripts (${scripts.join(", ")}): name the one to run with --script <file>.`
+    );
+  }
+  return scripts[0];
+}
+async function runNote(config, ref, id) {
+  const { forkPath } = config;
+  const { note, target, files } = await writeNoteFolder(config, ref, id);
+  const script = join11(target, resolveCodemod(id, files, config.script));
+  const args = config.runArgs?.length ? config.runArgs : ["inventory", ...note.roots];
+  const upstreamCommit = await readManifestBase(forkPath) ?? ref;
+  await ensureUpstreamCommit(config, upstreamCommit);
+  const identical = await listIdenticalToRef(forkPath, upstreamCommit);
+  console.info(colors_default.dim(`running pnpm exec tsx ${script} ${args.join(" ")}`));
+  console.info();
+  const child = spawnSync("pnpm", ["exec", "tsx", script, ...args], { cwd: forkPath, stdio: "inherit" });
+  if (child.error) throw new Error(`could not run the codemod: ${child.error.message}`);
+  const stillIdentical = await listIdenticalToRef(forkPath, upstreamCommit);
+  const restored = [...identical].filter((path) => !stillIdentical.has(path)).sort();
+  await batchRestoreWorktreeFromRef(forkPath, upstreamCommit, restored);
+  const upstreamShort = upstreamCommit.slice(0, 9);
+  console.info();
+  if (restored.length > 0) {
+    console.info(`${checkMark} restored ${restored.length} file(s) to upstream ${upstreamShort}`);
+    console.info(colors_default.dim("  the codemod changed them, and they were identical to upstream before the run:"));
+    for (const path of restored.slice(0, RESTORED_LIST_MAX)) console.info(colors_default.dim(`    ${path}`));
+    if (restored.length > RESTORED_LIST_MAX) {
+      console.info(colors_default.dim(`    ... + ${restored.length - RESTORED_LIST_MAX} more`));
+    }
+  } else {
+    console.info(colors_default.dim(`no file identical to upstream ${upstreamShort} was changed by the codemod.`));
+  }
+  if (child.status !== 0) throw new Error(`the codemod exited with code ${child.status ?? "unknown"}`);
+  if (!config.runArgs?.length) {
+    const apply = ["rewrite", ...note.roots].join(" ");
+    console.info(colors_default.dim(`report only. to apply: pnpm cella migrate --run ${id} -- ${apply}`));
+  }
 }
 async function markNotes(config, ref, pending, ids) {
   const open = new Set(pending);
@@ -2909,7 +3110,7 @@ async function markNotes(config, ref, pending, ids) {
   for (const id of ids) open.delete(id);
   await writePending(config.forkPath, [...open]);
   const marked = ids.length - unknown.length;
-  if (marked > 0) console.info(`${colors_default.green("\u2713")} recorded ${marked} note(s) as handled`);
+  if (marked > 0) console.info(`${checkMark} recorded ${marked} note(s) as handled`);
   if (unknown.length > 0) console.info(colors_default.dim(`not pending, left as is: ${unknown.join(", ")}`));
   console.info(colors_default.dim(formatNotesLine((await listNoteIds(config.forkPath, ref)).length, open.size)));
 }
@@ -2924,6 +3125,7 @@ async function runMigrate(config) {
   const githubUrl = getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0;
   const urlOf = (id) => noteUrl(githubUrl, ref, id);
   if (config.mark?.length) return markNotes(config, ref, pending, config.mark);
+  if (config.run) return runNote(config, ref, config.run);
   if (config.extract) return extractNote(config, ref, config.extract);
   if (config.show) {
     const source = await git(["show", `${ref}:${NOTES_DIR}/${config.show}/README.md`], forkPath, {
@@ -2997,16 +3199,7 @@ function printUnifiedDiff(config, filePath) {
 }
 async function runAnalyze(config) {
   createSpinner("starting analysis...");
-  const result = await runMergeEngine(config, {
-    apply: false,
-    onProgress: (message) => {
-      spinnerText(message);
-    },
-    onStep: (label, detail) => {
-      spinnerSuccess(label, detail);
-      createSpinner("...");
-    }
-  });
+  const result = await runEngineWithSpinner(config, false);
   spinnerSuccess();
   const scopedFiles = filterByScope(result, config.scope ?? "all");
   if (config.diff) {
@@ -3028,15 +3221,15 @@ async function runAnalyze(config) {
       upstreamChangedLines: f.upstreamChangedLines ?? null,
       upstreamLinesAbsent: f.upstreamLinesAbsent ?? null,
       upstreamOnly: f.upstreamOnly ?? false,
-      // Only on the sync config: upstream override entries the fork config does not follow
-      upstreamOverrides: overrides && f.path === CONFIG_FILE ? { pinned: overrides.pinned, ignored: overrides.ignored } : null
+      // 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
     }));
     writeStdout(JSON.stringify(out, null, 2));
     return result;
   }
   if (config.list) {
     for (const file of scopedFiles) {
-      console.info(file.path);
+      writeStdout(file.path);
     }
     return result;
   }
@@ -3045,7 +3238,7 @@ async function runAnalyze(config) {
     if (!file) throw new Error(`file not found in analysis results: ${config.openDiff}`);
     const patch = gitDiffFile(config.forkPath, config.upstreamRef, file.path);
     if (patch.length === 0) {
-      console.info(`${colors_default.green("\u2713")} ${file.path} is identical to upstream`);
+      console.info(`${checkMark} ${file.path} is identical to upstream`);
       return result;
     }
     const pagePath = await openDiffInBrowser(
@@ -3058,7 +3251,7 @@ async function runAnalyze(config) {
       },
       config.forkPath
     );
-    console.info(`${colors_default.green("\u2713")} opened browser diff for ${file.path}`);
+    console.info(`${checkMark} opened browser diff for ${file.path}`);
     console.info(colors_default.dim(`  ${pagePath}`));
     return result;
   }
@@ -3068,41 +3261,34 @@ async function runAnalyze(config) {
     fileLinkMode: config.settings.fileLinkMode,
     forkPath: config.forkPath
   };
-  printAnalysisFileGroups(result.files, linkOptions);
-  printSummary(result.summary, "analysis summary");
-  printIgnoredUpstreamChanges(result);
-  printUpstreamOverrideChanges(result);
-  printMaskingPinWarning(result.files);
+  printAnalysisFileGroups(result.files, linkOptions, result);
+  printEngineReports(result, "analysis summary");
   await printMigrationNotesLine(config, result);
-  if (config.logFile) {
-    const logPath = writeLogFile(config.forkPath, result.files);
-    console.info();
-    console.info(colors_default.dim(`full file list written to: ${logPath}`));
-  }
+  printLogFileReport(config, result.files);
   console.info();
   return result;
 }
 
 // src/services/audit.ts
-import { spawnSync } from "child_process";
-import * as fs2 from "fs";
-import * as path2 from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { readFileSync as readFileSync3 } from "fs";
+import { basename as basename5, join as join13, relative as relative2 } from "path";
 import { checkbox, confirm, Separator } from "@inquirer/prompts";
 
 // src/utils/audit-utils.ts
 import { execFile as execFile2 } from "child_process";
-import * as fs from "fs";
-import * as path from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync2, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
+import { join as join12 } from "path";
 import { promisify as promisify2 } from "util";
 var execFileAsync2 = promisify2(execFile2);
-var CACHE_FILE = path.join(import.meta.dirname, "..", "..", ".audit.cache.json");
+var CACHE_FILE = join12(import.meta.dirname, "..", "..", ".audit.cache.json");
 var CACHE_TTL = 7 * 24 * 60 * 60 * 1e3;
 var CHANGELOG_PATHS = ["CHANGELOG.md", "CHANGELOG", "changelog.md", "HISTORY.md", "CHANGES.md", "NEWS.md"];
 var DEFAULT_BRANCHES = ["main", "master"];
 function loadCache() {
   try {
-    if (fs.existsSync(CACHE_FILE)) {
-      return JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
+    if (existsSync8(CACHE_FILE)) {
+      return JSON.parse(readFileSync2(CACHE_FILE, "utf8"));
     }
   } catch {
   }
@@ -3110,15 +3296,15 @@ function loadCache() {
 }
 function saveCache(cache) {
   try {
-    fs.writeFileSync(CACHE_FILE, `${JSON.stringify(cache, null, 2)}
+    writeFileSync3(CACHE_FILE, `${JSON.stringify(cache, null, 2)}
 `);
   } catch {
   }
 }
 function clearCache() {
   try {
-    if (fs.existsSync(CACHE_FILE)) {
-      fs.unlinkSync(CACHE_FILE);
+    if (existsSync8(CACHE_FILE)) {
+      unlinkSync(CACHE_FILE);
       console.info(colors_default.green("\u2713 cache cleared successfully"));
     } else {
       console.info(colors_default.yellow("no cache file found"));
@@ -3206,56 +3392,32 @@ function isMajorVersionChange(current, latest) {
   if (!currentMajor || !latestMajor) return false;
   return Number.parseInt(latestMajor, 10) > Number.parseInt(currentMajor, 10);
 }
-async function getOutdatedPackages(cwd) {
+async function runPnpmJson(args, cwd) {
+  const parse = (stdout) => {
+    if (!stdout || stdout.trim() === "") return null;
+    try {
+      return JSON.parse(stdout);
+    } catch {
+      return null;
+    }
+  };
   try {
-    const { stdout } = await execFileAsync2("pnpm", ["-r", "outdated", "--json"], {
-      encoding: "utf-8",
+    const { stdout } = await execFileAsync2("pnpm", args, {
+      encoding: "utf8",
       maxBuffer: 10 * 1024 * 1024,
       // 10MB buffer for large outputs
       cwd
     });
-    if (!stdout || stdout.trim() === "") {
-      return {};
-    }
-    return JSON.parse(stdout);
+    return parse(stdout);
   } catch (error) {
-    if (error instanceof Error && "stdout" in error) {
-      const stdout = error.stdout;
-      if (stdout?.trim()) {
-        try {
-          return JSON.parse(stdout);
-        } catch {
-          return {};
-        }
-      }
-    }
-    return {};
+    return parse(error instanceof Error && "stdout" in error ? error.stdout : void 0);
   }
 }
+async function getOutdatedPackages(cwd) {
+  return await runPnpmJson(["-r", "outdated", "--json"], cwd) ?? {};
+}
 async function runPnpmAudit(cwd) {
-  try {
-    const { stdout } = await execFileAsync2("pnpm", ["audit", "--json"], {
-      encoding: "utf-8",
-      maxBuffer: 10 * 1024 * 1024,
-      cwd
-    });
-    if (!stdout || stdout.trim() === "") {
-      return null;
-    }
-    return JSON.parse(stdout);
-  } catch (error) {
-    if (error instanceof Error && "stdout" in error) {
-      const stdout = error.stdout;
-      if (stdout?.trim()) {
-        try {
-          return JSON.parse(stdout);
-        } catch {
-          return null;
-        }
-      }
-    }
-    return null;
-  }
+  return await runPnpmJson(["audit", "--json"], cwd);
 }
 function parseDependencyPath(paths) {
   for (const pathStr of paths) {
@@ -3277,12 +3439,9 @@ function buildVulnerabilityMap(auditResult) {
     const { workspace, directDependency } = parseDependencyPath(allPaths);
     const existing = map.get(advisory.module_name) || [];
     existing.push({
-      id: advisory.id,
       title: advisory.title,
       severity: advisory.severity,
-      url: advisory.url,
       vulnerableVersions: advisory.vulnerable_versions,
-      patchedVersions: advisory.patched_versions,
       cves: advisory.cves || [],
       workspace,
       directDependency
@@ -3291,19 +3450,15 @@ function buildVulnerabilityMap(auditResult) {
   }
   return map;
 }
+var vulnIcons = {
+  critical: colors_default.red("\u25CF"),
+  high: colors_default.red("\u25CF"),
+  moderate: colors_default.yellow("\u25CF"),
+  low: colors_default.blue("\u25CF"),
+  info: colors_default.gray("\u25CF")
+};
 function getVulnIcon(severity) {
-  switch (severity) {
-    case "critical":
-      return colors_default.red("\u25CF");
-    case "high":
-      return colors_default.red("\u25CF");
-    case "moderate":
-      return colors_default.yellow("\u25CF");
-    case "low":
-      return colors_default.blue("\u25CF");
-    default:
-      return colors_default.gray("\u25CF");
-  }
+  return vulnIcons[severity] ?? colors_default.gray("\u25CF");
 }
 function getHighestSeverity(vulns) {
   if (vulns.length === 0) return null;
@@ -3313,13 +3468,13 @@ function getHighestSeverity(vulns) {
   }
   return null;
 }
-function middleTruncate(str, maxLen) {
-  if (str.length <= maxLen) return str;
+function middleTruncate(str2, maxLen) {
+  if (str2.length <= maxLen) return str2;
   const ellipsis = "\u2026";
   const charsToShow = maxLen - ellipsis.length;
   const frontChars = Math.ceil(charsToShow / 2);
   const backChars = Math.floor(charsToShow / 2);
-  return str.slice(0, frontChars) + ellipsis + str.slice(-backChars);
+  return str2.slice(0, frontChars) + ellipsis + str2.slice(-backChars);
 }
 function formatDependents(dependents) {
   if (dependents.length === 0) return "";
@@ -3364,18 +3519,42 @@ function parseYamlBlockList(content, key) {
 }
 
 // src/services/audit.ts
-async function runAudit(config, options = {}) {
+var AUDIT_FIX_VALUE = "__audit_fix__";
+function createDependentPkgReader() {
+  const cache = /* @__PURE__ */ new Map();
+  return (location) => {
+    let cached = cache.get(location);
+    if (cached === void 0) {
+      try {
+        cached = JSON.parse(readFileSync3(join13(location, "package.json"), "utf8"));
+      } catch {
+        cached = null;
+      }
+      cache.set(location, cached ?? null);
+    }
+    return cached ?? null;
+  };
+}
+function formatSeverityCounts(counts, suffix = "") {
+  const parts = [];
+  if (counts.critical) parts.push(colors_default.red(`${counts.critical} critical${suffix}`));
+  if (counts.high) parts.push(colors_default.red(`${counts.high} high${suffix}`));
+  if (counts.moderate) parts.push(colors_default.yellow(`${counts.moderate} moderate${suffix}`));
+  if (counts.low) parts.push(colors_default.blue(`${counts.low} low`));
+  return parts;
+}
+async function runAudit(config) {
   const { forkPath } = config;
-  if (options.checkOverrides) {
+  if (config.checkOverrides) {
     await checkOverrides(forkPath);
     return;
   }
   const spinner = createSpinner("checking for outdated packages & vulnerabilities...");
   try {
-    if (options.force) {
+    if (config.force) {
       spinnerText("clearing pnpm metadata cache...");
       clearCache();
-      spawnSync("pnpm", ["cache", "delete", "*"], {
+      spawnSync2("pnpm", ["cache", "delete", "*"], {
         cwd: forkPath,
         stdio: "ignore"
       });
@@ -3389,25 +3568,13 @@ async function runAudit(config, options = {}) {
       return;
     }
     const cache = loadCache();
-    spinnerText(`found ${packageNames.length} outdated package(s) - fetching metadata...`);
-    const pkgJsonCache = /* @__PURE__ */ new Map();
-    const readDependentPkg = (location) => {
-      let cached = pkgJsonCache.get(location);
-      if (cached === void 0) {
-        try {
-          cached = JSON.parse(fs2.readFileSync(path2.join(location, "package.json"), "utf-8"));
-        } catch {
-          cached = null;
-        }
-        pkgJsonCache.set(location, cached ?? null);
-      }
-      return cached ?? null;
-    };
+    spinnerText(`found ${packageNames.length} outdated package(s), fetching metadata...`);
+    const readDependentPkg = createDependentPkgReader();
     const dependentNameCache = /* @__PURE__ */ new Map();
     for (const name of packageNames) {
       for (const dep of outdatedPackages[name].dependentPackages) {
         if (!dependentNameCache.has(dep.location)) {
-          dependentNameCache.set(dep.location, readDependentPkg(dep.location)?.name || path2.basename(dep.location));
+          dependentNameCache.set(dep.location, readDependentPkg(dep.location)?.name || basename5(dep.location));
         }
       }
     }
@@ -3518,7 +3685,7 @@ function printOutdatedResults(enhancedPackages, dependentNameCache, forkPath) {
   const dependentMap = /* @__PURE__ */ new Map();
   for (const pkg of enhancedPackages) {
     for (const loc of pkg.dependentLocations) {
-      const dependentName = dependentNameCache.get(loc) || path2.basename(loc);
+      const dependentName = dependentNameCache.get(loc) || basename5(loc);
       const existing = dependentMap.get(dependentName);
       if (existing) {
         existing.count++;
@@ -3530,34 +3697,15 @@ function printOutdatedResults(enhancedPackages, dependentNameCache, forkPath) {
   const sortedDependents = [...dependentMap.entries()].sort((a, b) => a[0].localeCompare(b[0]));
   const maxDependentNameLen = Math.max(0, ...sortedDependents.map(([name]) => name.length));
   for (const [dependentName, { location, count }] of sortedDependents) {
-    const packageJsonPath2 = path2.join(location, "package.json");
-    const relativePath = path2.relative(forkPath, packageJsonPath2);
+    const packageJsonPath2 = join13(location, "package.json");
+    const relativePath = relative2(forkPath, packageJsonPath2);
     const paddedName = dependentName.padEnd(maxDependentNameLen);
     console.info(
       `  ${colors_default.dim("\u2022")} ${paddedName}  ${hyperlink(relativePath, `file://${packageJsonPath2}`)} ${colors_default.dim(`${count}`)}`
     );
   }
 }
-async function promptForUpdates(packages, forkPath, auditResult) {
-  const hasVulnerabilities = auditResult !== null && Object.values(auditResult.metadata?.vulnerabilities || {}).some((c) => c > 0);
-  const hasPackages = packages.length > 0;
-  let confirmMessage = "update packages?";
-  if (hasVulnerabilities && hasPackages) {
-    confirmMessage = "update packages and fix vulnerabilities?";
-  } else if (hasVulnerabilities) {
-    confirmMessage = "fix vulnerabilities?";
-  }
-  let wantsUpdate;
-  try {
-    wantsUpdate = await confirm({
-      message: confirmMessage,
-      default: true
-    });
-  } catch {
-    return;
-  }
-  if (!wantsUpdate) return;
-  console.info();
+function buildUpdateChoices(packages, auditResult, hasVulnerabilities) {
   const makeChoice = (pkg) => {
     const devTag = pkg.isDev ? colors_default.dim(" (dev)") : "";
     const version = `${colors_default.red(pkg.current)} \u2192 ${colors_default.green(pkg.latest)}`;
@@ -3568,17 +3716,11 @@ async function promptForUpdates(packages, forkPath, auditResult) {
       checked: false
     };
   };
-  const AUDIT_FIX_VALUE = "__audit_fix__";
   const pinned = packages.filter((p) => p.pinnedIn.length > 0);
   const regular = packages.filter((p) => p.pinnedIn.length === 0);
   const choices = [];
   if (hasVulnerabilities) {
-    const vulnMeta = auditResult?.metadata?.vulnerabilities || {};
-    const parts = [];
-    if (vulnMeta.critical) parts.push(colors_default.red(`${vulnMeta.critical} critical`));
-    if (vulnMeta.high) parts.push(colors_default.red(`${vulnMeta.high} high`));
-    if (vulnMeta.moderate) parts.push(colors_default.yellow(`${vulnMeta.moderate} moderate`));
-    if (vulnMeta.low) parts.push(colors_default.blue(`${vulnMeta.low} low`));
+    const parts = formatSeverityCounts(auditResult?.metadata?.vulnerabilities || {});
     const vulnSummary = parts.length > 0 ? ` ${colors_default.dim("\xB7")} ${parts.join(" ")}` : "";
     choices.push(new Separator(colors_default.red(`\u2500\u2500 vulnerabilities${vulnSummary} \u2500\u2500`)));
     choices.push({
@@ -3597,6 +3739,29 @@ async function promptForUpdates(packages, forkPath, auditResult) {
     }
     choices.push(...regular.map(makeChoice));
   }
+  return choices;
+}
+async function promptForUpdates(packages, forkPath, auditResult) {
+  const hasVulnerabilities = auditResult !== null && Object.values(auditResult.metadata?.vulnerabilities || {}).some((c) => c > 0);
+  const hasPackages = packages.length > 0;
+  let confirmMessage = "update packages?";
+  if (hasVulnerabilities && hasPackages) {
+    confirmMessage = "update packages and fix vulnerabilities?";
+  } else if (hasVulnerabilities) {
+    confirmMessage = "fix vulnerabilities?";
+  }
+  let wantsUpdate;
+  try {
+    wantsUpdate = await confirm({
+      message: confirmMessage,
+      default: true
+    });
+  } catch {
+    return;
+  }
+  if (!wantsUpdate) return;
+  console.info();
+  const choices = buildUpdateChoices(packages, auditResult, hasVulnerabilities);
   let selected;
   try {
     selected = await checkbox({
@@ -3624,6 +3789,9 @@ async function promptForUpdates(packages, forkPath, auditResult) {
   }
   const runAuditFix = selected.includes(AUDIT_FIX_VALUE);
   const selectedPackages = selected.filter((s) => s !== AUDIT_FIX_VALUE);
+  await executeUpdates(packages, forkPath, selectedPackages, runAuditFix);
+}
+async function executeUpdates(packages, forkPath, selectedPackages, runAuditFix) {
   const summaryParts = [];
   if (selectedPackages.length > 0) {
     summaryParts.push(`updating ${selectedPackages.length} package${selectedPackages.length !== 1 ? "s" : ""}`);
@@ -3655,17 +3823,15 @@ async function promptForUpdates(packages, forkPath, auditResult) {
   for (const pkgName of selectedPackages) {
     const pkg = packages.find((p) => p.name === pkgName);
     if (!pkg) continue;
-    for (let i = 0; i < pkg.dependents.length; i++) {
-      const dependent = pkg.dependents[i];
-      if (!workspacePackages.has(dependent)) {
-        workspacePackages.set(dependent, { packages: [] });
-      }
-      workspacePackages.get(dependent)?.packages.push(pkgName);
+    for (const dependent of pkg.dependents) {
+      const group = workspacePackages.get(dependent);
+      if (group) group.push(pkgName);
+      else workspacePackages.set(dependent, [pkgName]);
     }
   }
   if (runAuditFix) {
     console.info(colors_default.dim("running pnpm audit --fix override..."));
-    const auditFixResult = spawnSync("pnpm", ["audit", "--fix", "override"], {
+    const auditFixResult = spawnSync2("pnpm", ["audit", "--fix", "override"], {
       cwd: forkPath,
       stdio: "inherit"
     });
@@ -3676,7 +3842,7 @@ async function promptForUpdates(packages, forkPath, auditResult) {
       console.error(colors_default.red(`\u2717 pnpm audit --fix override failed (exit code ${auditFixResult.status})`));
     }
   }
-  for (const [workspace, { packages: pkgs }] of workspacePackages) {
+  for (const [workspace, pkgs] of workspacePackages) {
     const pkgList = pkgs.join(", ");
     console.info(`${colors_default.cyan("\u2191")} ${colors_default.bold(workspace)}: ${colors_default.dim(pkgList)}`);
   }
@@ -3685,7 +3851,7 @@ async function promptForUpdates(packages, forkPath, auditResult) {
     const selectedCatalogPackages = selectedPackages.filter((pkgName) => catalogPackages.has(pkgName));
     if (selectedCatalogPackages.length > 0) {
       console.info(colors_default.dim(`normalizing catalog consumers: ${selectedCatalogPackages.join(", ")}`));
-      const normalizeResult = spawnSync("pnpm", ["-r", "up", ...selectedCatalogPackages], {
+      const normalizeResult = spawnSync2("pnpm", ["-r", "up", ...selectedCatalogPackages], {
         cwd: forkPath,
         stdio: "inherit"
       });
@@ -3695,7 +3861,7 @@ async function promptForUpdates(packages, forkPath, auditResult) {
         return;
       }
     }
-    const result = spawnSync("pnpm", ["-r", "up", "--latest", ...selectedPackages], {
+    const result = spawnSync2("pnpm", ["-r", "up", "--latest", ...selectedPackages], {
       cwd: forkPath,
       stdio: "inherit"
     });
@@ -3710,15 +3876,11 @@ async function promptForUpdates(packages, forkPath, auditResult) {
 function printVulnerabilityResults(auditResult, vulnMap) {
   if (auditResult && vulnMap.size > 0) {
     const vulnMeta = auditResult.metadata?.vulnerabilities || {};
-    const criticalCount = vulnMeta.critical || 0;
-    const highCount = vulnMeta.high || 0;
-    const moderateCount = vulnMeta.moderate || 0;
-    const lowCount = vulnMeta.low || 0;
     console.info();
     console.info(
-      `${colors_default.red("\u26A0")} ${colors_default.bold("vulnerabilities")} ${colors_default.dim("\xB7")} ` + (criticalCount > 0 ? colors_default.red(`${criticalCount} critical `) : "") + (highCount > 0 ? colors_default.red(`${highCount} high `) : "") + (moderateCount > 0 ? colors_default.yellow(`${moderateCount} moderate `) : "") + (lowCount > 0 ? colors_default.blue(`${lowCount} low`) : "")
+      `${colors_default.red("\u26A0")} ${colors_default.bold("vulnerabilities")} ${colors_default.dim("\xB7")} ${formatSeverityCounts(vulnMeta, " ").join("")}`
     );
-    console.info("\u2500".repeat(60));
+    console.info(DIVIDER);
     for (const [pkgName, vulns] of vulnMap.entries()) {
       for (const vuln of vulns) {
         const severityIcon = getVulnIcon(vuln.severity);
@@ -3738,14 +3900,14 @@ function printVulnerabilityResults(auditResult, vulnMap) {
     }
   } else {
     console.info();
-    console.info(`${colors_default.green("\u2713")} no vulnerabilities found`);
+    console.info(`${checkMark} no vulnerabilities found`);
   }
   console.info();
 }
 function readCatalogPackageNames(forkPath) {
-  const workspacePath = path2.join(forkPath, "pnpm-workspace.yaml");
+  const workspacePath = join13(forkPath, "pnpm-workspace.yaml");
   try {
-    const content = fs2.readFileSync(workspacePath, "utf-8");
+    const content = readFileSync3(workspacePath, "utf8");
     return new Set(Object.keys(parseYamlBlockMap(content, "catalog")));
   } catch {
     return /* @__PURE__ */ new Set();
@@ -3753,18 +3915,18 @@ function readCatalogPackageNames(forkPath) {
 }
 function readOverrides(forkPath) {
   const overrides = /* @__PURE__ */ new Map();
-  const pkgJsonPath = path2.join(forkPath, "package.json");
+  const pkgJsonPath = join13(forkPath, "package.json");
   try {
-    const pkgJson = JSON.parse(fs2.readFileSync(pkgJsonPath, "utf-8"));
+    const pkgJson = JSON.parse(readFileSync3(pkgJsonPath, "utf8"));
     const pnpmOverrides = pkgJson.pnpm?.overrides || {};
     for (const [key, value] of Object.entries(pnpmOverrides)) {
       overrides.set(key, { target: value, source: "package.json" });
     }
   } catch {
   }
-  const workspacePath = path2.join(forkPath, "pnpm-workspace.yaml");
+  const workspacePath = join13(forkPath, "pnpm-workspace.yaml");
   try {
-    const content = fs2.readFileSync(workspacePath, "utf-8");
+    const content = readFileSync3(workspacePath, "utf8");
     const wsOverrides = parseYamlBlockMap(content, "overrides");
     for (const [key, value] of Object.entries(wsOverrides)) {
       overrides.set(key, { target: value, source: "pnpm-workspace.yaml" });
@@ -3807,7 +3969,7 @@ async function checkOverrides(forkPath) {
   const maxTargetLen = Math.max(6, ...allValues.map((v) => v.target.length));
   if (securityOverrides.length > 0) {
     console.info(colors_default.bold(`security overrides (${securityOverrides.length})`));
-    console.info("\u2500".repeat(60));
+    console.info(DIVIDER);
     for (const o of securityOverrides) {
       const icon = o.status === "active" ? colors_default.red("\u25CF") : colors_default.green("\u25CB");
       const statusText = o.status === "active" ? colors_default.red("active") : colors_default.green("likely stale");
@@ -3820,7 +3982,7 @@ async function checkOverrides(forkPath) {
   }
   if (pinOverrides.length > 0) {
     console.info(colors_default.bold(`version pins (${pinOverrides.length})`));
-    console.info("\u2500".repeat(60));
+    console.info(DIVIDER);
     for (const o of pinOverrides) {
       const keyText = colors_default.white(o.key.padEnd(maxKeyLen));
       const targetText = colors_default.dim(o.target.padEnd(maxTargetLen));
@@ -3833,26 +3995,24 @@ async function checkOverrides(forkPath) {
   const activeCount = securityOverrides.filter((o) => o.status === "active").length;
   if (staleCount > 0) {
     console.info(
-      `${colors_default.green("\u25CB")} ${staleCount} override${staleCount !== 1 ? "s" : ""} likely stale \u2014 no matching advisory found in current audit`
+      `${colors_default.green("\u25CB")} ${staleCount} override${staleCount !== 1 ? "s" : ""} likely stale: no matching advisory found in current audit`
     );
-    console.info(colors_default.dim("  overrides mask vulnerabilities \u2014 verify by temporarily removing and running pnpm audit"));
+    console.info(colors_default.dim("  overrides mask vulnerabilities: verify by temporarily removing and running pnpm audit"));
   }
   if (activeCount > 0) {
     console.info(
-      `${colors_default.red("\u25CF")} ${activeCount} override${activeCount !== 1 ? "s" : ""} still active \u2014 advisory present without override`
+      `${colors_default.red("\u25CF")} ${activeCount} override${activeCount !== 1 ? "s" : ""} still active: advisory present without override`
     );
   }
   if (pinOverrides.length > 0) {
     console.info(
-      `${colors_default.blue("\u25C6")} ${pinOverrides.length} version pin${pinOverrides.length !== 1 ? "s" : ""} \u2014 not security-related, review manually`
+      `${colors_default.blue("\u25C6")} ${pinOverrides.length} version pin${pinOverrides.length !== 1 ? "s" : ""}: not security-related, review manually`
     );
   }
   console.info();
 }
 
 // src/services/contributions.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { join as join16 } from "path";
 import {
   createPrompt,
   isDownKey,
@@ -3860,14 +4020,13 @@ import {
   isSpaceKey,
   isUpKey,
   useKeypress,
-  useMemo,
   usePagination,
   useState
 } from "@inquirer/core";
 import { select as select2 } from "@inquirer/prompts";
 
 // src/services/contrib-core.ts
-import { dirname as dirname5, join as join15, resolve as resolve5 } from "path";
+import { dirname as dirname5, join as join14, resolve as resolve5 } from "path";
 async function listFilesAtRef(repoPath, ref) {
   const raw = await git(["ls-tree", "-r", "--name-only", ref], repoPath);
   return new Set(raw.split("\n").filter(Boolean));
@@ -3875,8 +4034,8 @@ async function listFilesAtRef(repoPath, ref) {
 async function detectContributableFiles(repoPath, baseRef, forkRef, config, forkTerritory = []) {
   const mergeBase = (await git(["merge-base", baseRef, forkRef], repoPath, { ignoreErrors: true })).trim() || baseRef;
   const predicates = {
-    isIgnored: (path4) => isIgnored(path4, config) || isUnderAnyFolder(path4, forkTerritory),
-    isPinned: (path4) => isPinned(path4, config)
+    isIgnored: (path) => isIgnored(path, config) || isUnderAnyFolder(path, forkTerritory),
+    isPinned: (path) => isPinned(path, config)
   };
   const analyzed = await analyzeRefs(repoPath, baseRef, forkRef, mergeBase, predicates);
   await enrichChangeInfo(repoPath, analyzed, mergeBase, baseRef, forkRef);
@@ -3931,7 +4090,7 @@ async function readBlobInfo(repoPath, ref, filePath) {
 async function buildContribBranch(repoPath, baseRef, forkRef, detection, forkName) {
   const branch = `contrib/${forkName}`;
   const gitDir = resolve5(repoPath, await git(["rev-parse", "--git-dir"], repoPath));
-  const tmpIndex = join15(gitDir, `tmp-contrib-index-${forkName.replace(/[^\w.-]/g, "_")}`);
+  const tmpIndex = join14(gitDir, `tmp-contrib-index-${forkName.replace(/[^\w.-]/g, "_")}`);
   const indexEnv = { GIT_INDEX_FILE: tmpIndex };
   try {
     await git(["read-tree", baseRef], repoPath, { env: indexEnv });
@@ -4004,20 +4163,14 @@ async function showContribDiff(item, baseRef, cwd, forkName) {
   if (patch.length === 0) return null;
   return openDiffInBrowser(patch.toString(), { filePath: item.path, srcLabel: "cella", dstLabel: forkName }, cwd);
 }
-function shouldApplyContributionsUnstaged(repoPath) {
-  return JSON.parse(readFileSync4(join16(repoPath, "package.json"), "utf8")).name === "cella";
-}
 var contribPrompt = createPrompt((config, done) => {
   const { pageSize = 20, baseRef, cwd, forkName } = config;
   const [items, setItems] = useState(config.items);
   const [active, setActive] = useState(0);
   const [statusMsg, setStatusMsg] = useState("");
   const [promptStatus, setPromptStatus] = useState("idle");
-  const bounds = useMemo(() => {
-    if (items.length === 0) return { first: 0, last: 0 };
-    return { first: 0, last: items.length - 1 };
-  }, [items]);
   useKeypress(async (key) => {
+    const last = items.length - 1;
     if (items.length === 0) {
       if (isEnterKey(key) || key.name === "q") {
         setPromptStatus("done");
@@ -4041,22 +4194,22 @@ var contribPrompt = createPrompt((config, done) => {
       return;
     }
     if (key.ctrl && isUpKey(key)) {
-      setActive(bounds.first);
+      setActive(0);
       setStatusMsg("");
       return;
     }
     if (key.ctrl && isDownKey(key)) {
-      setActive(bounds.last);
+      setActive(last);
       setStatusMsg("");
       return;
     }
     if (isUpKey(key)) {
-      setActive(active <= bounds.first ? bounds.first : active - 1);
+      setActive(active <= 0 ? 0 : active - 1);
       setStatusMsg("");
       return;
     }
     if (isDownKey(key)) {
-      setActive(active >= bounds.last ? bounds.last : active + 1);
+      setActive(active >= last ? last : active + 1);
       setStatusMsg("");
       return;
     }
@@ -4069,7 +4222,7 @@ var contribPrompt = createPrompt((config, done) => {
         const pagePath = await showContribDiff(items[active], baseRef, cwd, forkName);
         setStatusMsg(pagePath ? `opened ${items[active].path} in browser` : `no changes for ${items[active].path}`);
       } catch (error) {
-        setStatusMsg(`diff failed: ${error instanceof Error ? error.message : "unknown error"}`);
+        setStatusMsg(`diff failed: ${errorMessage(error)}`);
       }
       return;
     }
@@ -4083,12 +4236,12 @@ var contribPrompt = createPrompt((config, done) => {
   if (promptStatus === "done") {
     const checked = items.filter((i) => i.checked);
     if (checked.length > 0) {
-      return `${colors_default.green("\u2713")} ${checked.length} files accepted`;
+      return `${checkMark} ${checked.length} files accepted`;
     }
-    return `${colors_default.green("\u2713")} done`;
+    return `${checkMark} done`;
   }
   if (items.length === 0) {
-    return `${colors_default.green("\u2713")} no contributions \u2014 press enter`;
+    return `${checkMark} no contributions: press enter`;
   }
   const checkedCount = items.filter((i) => i.checked).length;
   const page = usePagination({
@@ -4122,6 +4275,38 @@ var contribPrompt = createPrompt((config, done) => {
   const lines = [header, page, statusLine, helpLine].filter(Boolean).join("\n").trimEnd();
   return `${lines}\x1B[?25l`;
 });
+async function selectFork(config, validated) {
+  if (config.fork) {
+    const match = validated.find((v) => v.fork.name === config.fork);
+    if (!match?.valid) {
+      throw new Error(`fork '${config.fork}' not found or invalid in config`);
+    }
+    return match;
+  }
+  const validForks = validated.filter((v) => v.valid);
+  if (config.list || config.json || config.diff) {
+    if (validForks.length === 0) {
+      throw new Error("no valid forks configured");
+    }
+    if (validForks.length > 1) {
+      throw new Error("multiple forks configured; pass --fork <name> to choose one");
+    }
+    return validForks[0];
+  }
+  const choices = validated.map((v) => ({
+    value: v.fork.name,
+    name: v.valid ? `${v.fork.name}  ${colors_default.dim(`[${v.fork.pullBranch}] ${v.fork.localPath}`)}` : `${v.fork.name}  ${colors_default.dim(v.fork.localPath)}`,
+    disabled: v.valid ? false : v.error ?? "invalid"
+  }));
+  const picked = await select2({
+    message: "select fork to pull contributions from:",
+    choices,
+    loop: false
+  });
+  const selected = validated.find((v) => v.fork.name === picked);
+  if (!selected) console.info(colors_default.dim("no fork selected."));
+  return selected;
+}
 async function fetchForkBranch(cellaPath, fetchSource, pullBranch) {
   await git(["fetch", fetchSource, pullBranch], cellaPath);
   return git(["rev-parse", "FETCH_HEAD"], cellaPath);
@@ -4149,42 +4334,8 @@ async function runContributions(config) {
   }
   const forkBasePath = await resolveForkBasePath(config.forkPath);
   const validated = forks.map((fork2) => validateForkPath(fork2, forkBasePath));
-  const validForks = validated.filter((v) => v.valid);
-  let selectedFork;
-  if (config.fork) {
-    const match = validated.find((v) => v.fork.name === config.fork);
-    if (!match?.valid) {
-      console.error(colors_default.red(`fork '${config.fork}' not found or invalid in config`));
-      return;
-    }
-    selectedFork = match;
-  } else if (config.list || config.json || config.diff) {
-    if (validForks.length === 0) {
-      console.error(colors_default.red("no valid forks configured"));
-      return;
-    }
-    if (validForks.length > 1) {
-      console.error(colors_default.red("multiple forks configured; pass --fork <name> to choose one"));
-      return;
-    }
-    selectedFork = validForks[0];
-  } else {
-    const choices = validated.map((v) => ({
-      value: v.fork.name,
-      name: v.valid ? `${v.fork.name}  ${colors_default.dim(`[${v.fork.pullBranch}] ${v.fork.localPath}`)}` : `${v.fork.name}  ${colors_default.dim(v.fork.localPath)}`,
-      disabled: v.valid ? false : v.error ?? "invalid"
-    }));
-    const picked = await select2({
-      message: "select fork to pull contributions from:",
-      choices,
-      loop: false
-    });
-    selectedFork = validated.find((v) => v.fork.name === picked);
-  }
-  if (!selectedFork) {
-    console.info(colors_default.dim("no fork selected."));
-    return;
-  }
+  const selectedFork = await selectFork(config, validated);
+  if (!selectedFork) return;
   const { fork, resolvedPath } = selectedFork;
   const forkName = fork.name;
   createSpinner("pulling fork contributions...");
@@ -4207,40 +4358,28 @@ async function runContributions(config) {
       if (appliedFiles.length > 0) {
         const stat = await getDiffStat(config.forkPath, baseRef, branch);
         const metaByPath = new Map(detection.files.map((f) => [f.path, f]));
-        for (const path4 of [...detection.modified, ...detection.created]) {
-          const fileMeta = metaByPath.get(path4);
-          allItems.push({
-            path: path4,
-            ref: branch,
-            deleted: false,
-            created: fileMeta?.kind === "created",
-            status: fileMeta?.status,
-            changedAt: fileMeta?.changedAt,
-            changedTs: fileMeta?.changedTs,
-            additions: stat.get(path4)?.additions ?? null,
-            deletions: stat.get(path4)?.deletions ?? null,
-            checked: false
-          });
-        }
-        for (const path4 of detection.deleted) {
-          const fileMeta = metaByPath.get(path4);
-          allItems.push({
-            path: path4,
+        const toItem = (path, deleted) => {
+          const fileMeta = metaByPath.get(path);
+          return {
+            path,
             ref: branch,
-            deleted: true,
+            deleted,
+            ...deleted ? {} : { created: fileMeta?.kind === "created" },
             status: fileMeta?.status,
             changedAt: fileMeta?.changedAt,
             changedTs: fileMeta?.changedTs,
-            additions: stat.get(path4)?.additions ?? null,
-            deletions: stat.get(path4)?.deletions ?? null,
+            additions: stat.get(path)?.additions ?? null,
+            deletions: stat.get(path)?.deletions ?? null,
             checked: false
-          });
-        }
+          };
+        };
+        for (const path of [...detection.modified, ...detection.created]) allItems.push(toItem(path, false));
+        for (const path of detection.deleted) allItems.push(toItem(path, true));
       }
     }
   } catch (error) {
     spinnerFail(`failed to pull ${forkName}`);
-    console.info(colors_default.red(`  \u2717 ${error instanceof Error ? error.message : "unknown error"}`));
+    console.info(colors_default.red(`  \u2717 ${errorMessage(error)}`));
     return;
   }
   if (allItems.length === 0) {
@@ -4251,15 +4390,13 @@ async function runContributions(config) {
   spinnerSuccess(`${allItems.length} files from ${forkName}`);
   if (!config.list && !config.diff && forkBanner) {
     console.info(
-      `  ${colors_default.dim(`${forkName}: comparing committed '${forkBanner.pullBranch}' @ ${forkBanner.sha} (${forkBanner.date}) \u2014 uncommitted fork changes are not included`)}`
+      `  ${colors_default.dim(`${forkName}: comparing committed '${forkBanner.pullBranch}' @ ${forkBanner.sha} (${forkBanner.date}); uncommitted fork changes are not included`)}`
     );
   }
   if (config.diff) {
     const matches = allItems.filter((i) => i.path === config.diff);
     if (matches.length === 0) {
-      console.error(colors_default.red(`no contribution found for path: ${config.diff}`));
-      process.exitCode = 1;
-      return;
+      throw new Error(`no contribution found for path: ${config.diff}`);
     }
     for (const item of matches) {
       const diff = gitDiffFile(config.forkPath, `${baseRef}..${item.ref}`, item.path, { dstPrefix: forkName });
@@ -4286,7 +4423,7 @@ async function runContributions(config) {
       const status = item.status ?? "behind";
       const kind = item.deleted ? "deleted" : "modified";
       const changedAt = item.changedAt ?? "-";
-      console.info(`${forkName}	${status}	${kind}	${changedAt}	${item.path}`);
+      writeStdout(`${forkName}	${status}	${kind}	${changedAt}	${item.path}`);
     }
     return;
   }
@@ -4305,7 +4442,7 @@ async function runContributions(config) {
     return;
   }
   createSpinner(`applying ${selected.length} files...`);
-  const applyUnstaged = shouldApplyContributionsUnstaged(config.forkPath);
+  const applyUnstaged = isUpstreamRepo(config.forkPath);
   let applied = 0;
   const errors = [];
   for (const item of selected) {
@@ -4329,7 +4466,7 @@ async function runContributions(config) {
       }
       applied++;
     } catch (error) {
-      errors.push(`${item.path}: ${error instanceof Error ? error.message : "unknown error"}`);
+      errors.push(`${item.path}: ${errorMessage(error)}`);
     }
   }
   if (errors.length > 0) {
@@ -4343,7 +4480,7 @@ async function runContributions(config) {
   console.info();
   console.info(
     colors_default.dim(
-      applyUnstaged ? "  files are unstaged \u2014 review, stage what you want, and commit when ready" : "  files are staged \u2014 review and commit when ready"
+      applyUnstaged ? "  files are unstaged: review, stage what you want, and commit when ready" : "  files are staged: review and commit when ready"
     )
   );
   console.info();
@@ -4355,16 +4492,16 @@ import process8 from "process";
 import { Separator as Separator2, select as select4 } from "@inquirer/prompts";
 
 // src/services/sync.ts
-import { spawnSync as spawnSync3 } from "child_process";
+import { spawnSync as spawnSync4 } from "child_process";
 import { select as select3 } from "@inquirer/prompts";
 
 // src/utils/gh.ts
-import { spawnSync as spawnSync2 } from "child_process";
+import { spawnSync as spawnSync3 } from "child_process";
 function ghAvailable() {
-  return spawnSync2("gh", ["--version"], { stdio: "ignore" }).status === 0;
+  return spawnSync3("gh", ["--version"], { stdio: "ignore" }).status === 0;
 }
 function runGh(cwd, args) {
-  const result = spawnSync2("gh", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+  const result = spawnSync3("gh", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
   const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
   return { ok: result.status === 0, output };
 }
@@ -4404,12 +4541,12 @@ function closePr(cwd, ref) {
 }
 
 // src/services/packages.ts
-import { existsSync as existsSync11, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
-import { join as join18 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
+import { join as join16 } from "path";
 
 // src/services/package-usage.ts
-import { existsSync as existsSync10, readFileSync as readFileSync5, statSync } from "fs";
-import { join as join17 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync4, statSync } from "fs";
+import { join as join15 } from "path";
 var MAX_FILE_BYTES = 1024 * 1024;
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -4417,41 +4554,41 @@ function escapeRegExp(value) {
 function readSearchable(filePath) {
   try {
     if (statSync(filePath).size > MAX_FILE_BYTES) return "";
-    const text = readFileSync5(filePath, "utf-8");
+    const text = readFileSync4(filePath, "utf8");
     return text.includes("\0") ? "" : text;
   } catch {
     return "";
   }
 }
-function fileSource(forkPath, path4) {
+function fileSource(forkPath, path) {
   let text;
-  return { path: path4, label: path4, text: () => text ??= readSearchable(join17(forkPath, path4)) };
+  return { path, label: path, text: () => text ??= readSearchable(join15(forkPath, path)) };
 }
-async function readScriptsAtRef(forkPath, ref, path4) {
+async function readScriptsAtRef(forkPath, ref, path) {
   try {
-    return JSON.parse(await git(["show", `${ref}:${path4}`], forkPath)).scripts ?? {};
+    return JSON.parse(await git(["show", `${ref}:${path}`], forkPath)).scripts ?? {};
   } catch {
     return {};
   }
 }
-async function scriptSources(forkPath, upstreamRef, baseRef, path4) {
+async function scriptSources(forkPath, upstreamRef, baseRef, path) {
   let forkScripts;
   try {
-    forkScripts = JSON.parse(readFileSync5(join17(forkPath, path4), "utf-8")).scripts ?? {};
+    forkScripts = JSON.parse(readFileSync4(join15(forkPath, path), "utf8")).scripts ?? {};
   } catch {
     return [];
   }
-  const baseScripts = await readScriptsAtRef(forkPath, baseRef, path4);
-  const upstreamScripts = await readScriptsAtRef(forkPath, upstreamRef, path4);
-  return Object.entries(forkScripts).filter(([name, value]) => value !== baseScripts[name] && value !== upstreamScripts[name]).map(([name, value]) => ({ path: path4, label: `${path4} (scripts.${name})`, text: () => value }));
+  const baseScripts = await readScriptsAtRef(forkPath, baseRef, path);
+  const upstreamScripts = await readScriptsAtRef(forkPath, upstreamRef, path);
+  return Object.entries(forkScripts).filter(([name, value]) => value !== baseScripts[name] && value !== upstreamScripts[name]).map(([name, value]) => ({ path, label: `${path} (scripts.${name})`, text: () => value }));
 }
 function binNames(forkPath, location, name) {
   const bareName = name.split("/").pop();
-  for (const dir of [join17(forkPath, location), forkPath]) {
-    const manifest = join17(dir, "node_modules", name, "package.json");
+  for (const dir of [join15(forkPath, location), forkPath]) {
+    const manifest = join15(dir, "node_modules", name, "package.json");
     if (!existsSync10(manifest)) continue;
     try {
-      const { bin } = JSON.parse(readFileSync5(manifest, "utf-8"));
+      const { bin } = JSON.parse(readFileSync4(manifest, "utf8"));
       if (typeof bin === "string") return [bareName];
       return bin && typeof bin === "object" ? Object.keys(bin) : [];
     } catch {
@@ -4476,9 +4613,9 @@ function scriptPattern(name) {
 async function loadForkUsage(forkPath, upstreamRef, baseRef) {
   const diff = await git(["diff", "--name-only", "-z", "--diff-filter=d", upstreamRef], forkPath);
   const sources = [];
-  for (const path4 of diff.split("\0").filter(Boolean)) {
-    if (isPackageJson(path4)) sources.push(...await scriptSources(forkPath, upstreamRef, baseRef, path4));
-    else if (!isManagedFile(path4)) sources.push(fileSource(forkPath, path4));
+  for (const path of diff.split("\0").filter(Boolean)) {
+    if (isPackageJson(path)) sources.push(...await scriptSources(forkPath, upstreamRef, baseRef, path));
+    else if (!isManagedFile(path)) sources.push(fileSource(forkPath, path));
   }
   const findIn = (scoped, patterns) => scoped.find((source) => patterns.some((pattern) => pattern.test(source.text())))?.label;
   return {
@@ -4631,14 +4768,14 @@ function setTopLevelKey(pkg, key, value) {
 function readPackageJson(filePath) {
   if (!existsSync11(filePath)) return null;
   try {
-    return JSON.parse(readFileSync6(filePath, "utf-8"));
+    return JSON.parse(readFileSync5(filePath, "utf8"));
   } catch {
     return null;
   }
 }
 function writePackageJson(filePath, data) {
   writeFileSync4(filePath, `${JSON.stringify(data, null, 2)}
-`, "utf-8");
+`, "utf8");
 }
 function packageJsonPath(relativePath) {
   return relativePath ? `${relativePath}/package.json` : "package.json";
@@ -4667,16 +4804,16 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
   const changes = [];
   const kept = [];
   const pkgRelPath = packageJsonPath(relativePath);
-  const pkgPath = join18(forkPath, pkgRelPath);
+  const pkgPath = join16(forkPath, pkgRelPath);
   const forkPkg = readPackageJson(pkgPath);
   const upstream = await readPackageJsonAtRef(forkPath, upstreamRef, relativePath);
   const basePkg = baseRef ? (await readPackageJsonAtRef(forkPath, baseRef, relativePath))?.data : void 0;
   if (!upstream) return { updated: false, changes, kept };
   if (!forkPkg) {
-    const workspaceArrived = relativePath !== "" && existsSync11(join18(forkPath, relativePath));
+    const workspaceArrived = relativePath !== "" && existsSync11(join16(forkPath, relativePath));
     if (basePkg || !workspaceArrived || isIgnored(pkgRelPath, config)) return { updated: false, changes, kept };
     writeFileSync4(pkgPath, upstream.raw.endsWith("\n") ? upstream.raw : `${upstream.raw}
-`, "utf-8");
+`, "utf8");
     return { updated: true, changes: ["copied from upstream (new workspace)"], kept };
   }
   const upstreamPkg = upstream.data;
@@ -4748,7 +4885,7 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
 }
 async function runPackages(config, options = {}) {
   createSpinner("syncing package.json files...");
-  const keysToSync = config.settings.packageJsonSync || ["dependencies", "devDependencies"];
+  const keysToSync = config.settings.packageJsonSync || DEFAULT_PACKAGE_JSON_SYNC;
   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;
@@ -4770,26 +4907,26 @@ async function runPackages(config, options = {}) {
     "package sync complete",
     `${changedCount} package.json${changedCount === 1 ? " was" : "s were"} changed`
   );
-  for (const { path: path4, changes } of reports) {
+  for (const { path, changes } of reports) {
     if (changes.length === 0) continue;
-    console.info(`  ${path4}`);
+    console.info(`  ${path}`);
     for (const change of changes) console.info(`    ${colors_default.dim(change)}`);
   }
-  const kept = reports.flatMap(({ path: path4, kept: kept2 }) => kept2.map((entry) => `${path4} ${entry}`));
+  const kept = reports.flatMap(({ path, kept: kept2 }) => kept2.map((entry) => `${path} ${entry}`));
   if (kept.length > 0) {
     console.info();
-    console.warn(
-      `${warningMark} kept ${kept.length} ${kept.length === 1 ? "entry" : "entries"} upstream dropped, the fork still uses ${kept.length === 1 ? "it" : "them"}:`
+    console.info(
+      `${warningMark} ${colors_default.yellow(`kept ${kept.length} ${kept.length === 1 ? "entry" : "entries"} upstream dropped, the fork still uses ${kept.length === 1 ? "it" : "them"}:`)}`
     );
-    for (const entry of kept) console.warn(`    ${colors_default.dim("\u2192")} ${entry}`);
+    for (const entry of kept) console.info(`    ${colors_default.dim("\u2192")} ${entry}`);
   }
   if (skipped.length > 0) {
     console.info();
-    console.warn(
-      `${warningMark} skipped ${skipped.length} conflicted package.json file(s) \u2014 resolve the conflicts, commit the merge, then rerun \`pnpm cella sync\`:`
+    console.info(
+      `${warningMark} ${colors_default.yellow(`skipped ${skipped.length} conflicted package.json file(s): resolve the conflicts, commit the merge, then rerun \`pnpm cella sync\`:`)}`
     );
-    for (const path4 of skipped) {
-      console.warn(`    ${colors_default.dim("\u2192")} ${path4}`);
+    for (const path of skipped) {
+      console.info(`    ${colors_default.dim("\u2192")} ${path}`);
     }
   }
 }
@@ -4797,14 +4934,14 @@ async function runPackages(config, options = {}) {
 // src/services/sync.ts
 async function resolveCycleStart(forkPath, base, currentBranch) {
   if (!await branchExists(forkPath, base)) {
-    await fetch2(forkPath, "origin").catch(() => {
+    await fetchRemote(forkPath, "origin").catch(() => {
     });
-    console.info(colors_default.dim(`'${base}' has no local branch \u2014 cutting from 'origin/${base}'.`));
+    console.info(colors_default.dim(`'${base}' has no local branch: cutting from 'origin/${base}'.`));
     return `origin/${base}`;
   }
   const { upstream, ahead, behind } = await getUpstreamStatus(forkPath, base);
   if (!upstream) {
-    console.info(colors_default.dim(`'${base}' has no upstream \u2014 skipping the up-to-date check.`));
+    console.info(colors_default.dim(`'${base}' has no upstream: skipping the up-to-date check.`));
     return base;
   }
   if (ahead > 0 && behind > 0) {
@@ -4817,7 +4954,7 @@ Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-
     const worktree = currentBranch === base ? null : await getBranchWorktree(forkPath, base);
     if (worktree) {
       console.info(
-        colors_default.dim(`'${base}' is ${behind} behind '${upstream}' but checked out at ${worktree} \u2014 leaving it as it is.`)
+        colors_default.dim(`'${base}' is ${behind} behind '${upstream}' but checked out at ${worktree}; leaving it as it is.`)
       );
       return upstream;
     }
@@ -4827,7 +4964,7 @@ Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-
     return base;
   }
   if (ahead > 0) {
-    console.info(colors_default.dim(`'${base}' is ${ahead} commit(s) ahead of '${upstream}' (unpushed) \u2014 continuing.`));
+    console.info(colors_default.dim(`'${base}' is ${ahead} commit(s) ahead of '${upstream}' (unpushed); continuing.`));
   }
   return base;
 }
@@ -4852,7 +4989,7 @@ async function resolveCutBase(forkPath, base) {
 async function returnToBase(forkPath, base) {
   const worktree = await getBranchWorktree(forkPath, base);
   if (worktree) {
-    console.info(colors_default.dim(`'${base}' is checked out at ${worktree} \u2014 detaching at '${base}' here instead...`));
+    console.info(colors_default.dim(`'${base}' is checked out at ${worktree}; detaching at '${base}' here instead...`));
     await switchDetached(forkPath, base);
     return `detached at '${base}'`;
   }
@@ -4864,30 +5001,24 @@ async function returnToBase(forkPath, base) {
 }
 async function runSync(config, options) {
   createSpinner("starting sync...");
-  const result = await runMergeEngine(config, {
-    apply: true,
-    onProgress: (message) => {
-      spinnerText(message);
-    },
-    onStep: (label, detail) => {
-      spinnerSuccess(label, detail);
-      createSpinner("...");
+  let result;
+  try {
+    result = await runEngineWithSpinner(config, true);
+  } catch (error) {
+    spinnerSuccess();
+    if (error instanceof UpstreamConfigChangedError) {
+      printUpstreamOverrideChanges({ upstreamOverrides: error.report });
+      console.info();
     }
-  });
+    throw error;
+  }
   if (result.success) {
     spinnerSuccess();
   } else {
     spinnerFail("sync completed with conflicts");
   }
-  printSummary(result.summary, "merge summary");
-  printIgnoredUpstreamChanges(result);
-  printUpstreamOverrideChanges(result);
-  printMaskingPinWarning(result.files);
-  if (config.logFile) {
-    const logPath = writeLogFile(config.forkPath, result.files);
-    console.info();
-    console.info(colors_default.dim(`full file list written to: ${logPath}`));
-  }
+  printEngineReports(result, "merge summary");
+  printLogFileReport(config, result.files);
   const stagedBranch = options?.stagedBranch && result.conflicts.length === 0 && hasStagedSyncChanges(result) ? options.stagedBranch : void 0;
   printSyncComplete(result, { stagedBranch });
   printFlagWarnings({ hard: config.hard, unpinned: config.unpinned });
@@ -4895,7 +5026,6 @@ async function runSync(config, options) {
   return result;
 }
 var SYNC_PR_TITLE = "chore: sync upstream cella";
-var PR_BODY_COMMIT_MAX = 50;
 async function buildSyncCommitMessage(forkPath, upstreamRef) {
   const shortSha = await getShortSha(forkPath, upstreamRef).catch(() => "");
   if (!shortSha) return SYNC_PR_TITLE;
@@ -4947,9 +5077,8 @@ async function buildSyncPrBodyForBranch(forkPath, base) {
   const version = manifest.upstream.release ?? await readPackageVersionAtRef(forkPath, toSha).catch(() => null);
   const totalCount = fromSha ? await countCommitsBetween(forkPath, fromSha, toSha).catch(() => 0) : 0;
   const commits = fromSha && totalCount > 0 ? await listCommitsBetween(forkPath, fromSha, toSha, {
-    oldestFirst: true,
-    skip: totalCount > PR_BODY_COMMIT_MAX ? totalCount - PR_BODY_COMMIT_MAX : 0,
-    limit: PR_BODY_COMMIT_MAX
+    skip: totalCount > COMMIT_LIST_MAX ? totalCount - COMMIT_LIST_MAX : 0,
+    limit: COMMIT_LIST_MAX
   }) : [];
   const notes = await readPrBodyNotes(forkPath, toSha, manifest.upstream.repo).catch(() => void 0);
   return buildSyncPrBody({ repoSlug: manifest.upstream.repo, version, fromSha, toSha, commits, totalCount, notes });
@@ -4973,11 +5102,8 @@ function printShipSteps(temporaryBranch, base, title) {
   console.info(colors_default.dim(`  git push -u origin ${temporaryBranch}`));
   printPrCreateStep(temporaryBranch, base, title);
 }
-function printFinishSteps() {
-  console.info(colors_default.dim("  pnpm cella sync"));
-}
 function hasStagedSyncChanges(result) {
-  return result.files.some((file) => ["behind", "diverged", "renamed", "ignored", "pinned"].includes(file.status));
+  return result.files.some((file) => SYNC_APPLIED_STATUSES.includes(file.status));
 }
 function extractFirstUrl(output) {
   return output.match(/https?:\/\/\S+/)?.[0];
@@ -4988,7 +5114,7 @@ async function flattenSyncBranch(forkPath, branch, base) {
   const message = await buildSyncCommitMessage(forkPath, `${mergeCommits[0]}^2`);
   console.info(
     colors_default.yellow(
-      `'${branch}' contains ${mergeCommits.length} merge commit(s) \u2014 the PR would list the entire upstream history.`
+      `'${branch}' contains ${mergeCommits.length} merge commit(s): the PR would list the entire upstream history.`
     )
   );
   console.info(colors_default.dim(`flattening '${branch}' to a single commit (same content)...`));
@@ -5011,8 +5137,7 @@ async function shipSyncBranch(config, branch) {
   try {
     await pushBranch(forkPath, "origin", branch, { forceWithLease: flattened });
   } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    console.info(colors_default.yellow(`push failed (${detail.split("\n")[0]}). finish manually:`));
+    console.info(colors_default.yellow(`push failed (${errorMessage(error).split("\n")[0]}). finish manually:`));
     printShipSteps(branch, base, prTitle);
     return;
   }
@@ -5020,9 +5145,9 @@ async function shipSyncBranch(config, branch) {
     console.info(colors_default.dim("opening a pull request..."));
     const prBody = await buildSyncPrBodyForBranch(forkPath, cutBase);
     const bodyArgs = prBody ? ["--body", prBody] : ["--fill"];
-    const pr = spawnSync3("gh", ["pr", "create", "--base", base, "--head", branch, "--title", prTitle, ...bodyArgs], {
+    const pr = spawnSync4("gh", ["pr", "create", "--base", base, "--head", branch, "--title", prTitle, ...bodyArgs], {
       cwd: forkPath,
-      encoding: "utf-8",
+      encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
     });
     prUrl = extractFirstUrl(`${pr.stdout ?? ""}
@@ -5034,16 +5159,16 @@ ${pr.stderr ?? ""}`);
       printPrCreateStep(branch, base, prTitle);
     }
   } else {
-    console.info(colors_default.yellow("`gh` not found \u2014 open the PR manually:"));
+    console.info(colors_default.yellow("`gh` not found, open the PR manually:"));
     printPrCreateStep(branch, base, prTitle);
   }
   const position = await returnToBase(forkPath, base);
   console.info();
   if (prUrl) {
-    console.info(`${colors_default.green("\u2713")} Sync pull request ${prOpened ? "opened" : "ready"}`);
+    console.info(`${checkMark} sync pull request ${prOpened ? "opened" : "ready"}`);
     console.info(colors_default.dim(`  ${prUrl} \xB7 branch pushed, ${position}`));
   } else {
-    console.info(`${colors_default.green("\u2713")} Sync branch pushed`);
+    console.info(`${checkMark} sync branch pushed`);
     console.info(colors_default.dim(`  '${branch}' is on origin, ${position}`));
   }
   await printMigrationNotesLine(config);
@@ -5051,23 +5176,43 @@ ${pr.stderr ?? ""}`);
 function finalizeWorkspace(forkPath) {
   for (const args of [["install"], ["check"]]) {
     console.info(colors_default.dim(`running pnpm ${args.join(" ")}...`));
-    const result = spawnSync3("pnpm", args, { cwd: forkPath, stdio: "inherit" });
+    const result = spawnSync4("pnpm", args, { cwd: forkPath, stdio: "inherit" });
     if (result.status !== 0) return false;
   }
   return true;
 }
+async function discardTemporarySyncBranch(forkPath, branch) {
+  if (branch.startBranch === "HEAD") await switchDetached(forkPath, branch.startCommit);
+  else await switchBranch(forkPath, branch.startBranch);
+  await deleteBranch(forkPath, branch.temporaryBranch);
+}
+async function discardUnusedSyncBranch(forkPath, branch) {
+  const unused = await getCurrentBranch(forkPath) === branch.temporaryBranch && !await mergeInProgress(forkPath) && await isClean(forkPath);
+  if (!unused) return false;
+  await discardTemporarySyncBranch(forkPath, branch);
+  const start = branch.startBranch === "HEAD" ? `at ${branch.startCommit.slice(0, 7)}` : `on '${branch.startBranch}'`;
+  console.info(colors_default.dim(`removed the unused '${branch.temporaryBranch}', back ${start}.`));
+  return true;
+}
 async function runSyncCycle(config) {
   const { forkPath } = config;
   const branch = await setupTemporarySyncBranch(config);
-  const result = await runSync(config, { stagedBranch: branch.temporaryBranch });
+  let result;
+  try {
+    result = await runSync(config, { stagedBranch: branch.temporaryBranch });
+  } catch (error) {
+    const discarded = await discardUnusedSyncBranch(forkPath, branch).catch(() => false);
+    if (discarded && error instanceof BehindSyncPointError && !config.ref) {
+      return { status: "noop", behind: error.message };
+    }
+    throw error;
+  }
   if (config.settings.syncWithPackages !== false) {
     await runPackages(config, { conflictedFiles: result.conflicts });
   }
   if (result.conflicts.length > 0) return { status: "conflicts", branch };
   if (!await mergeInProgress(forkPath)) {
-    if (branch.startBranch === "HEAD") await switchDetached(forkPath, branch.startCommit);
-    else await switchBranch(forkPath, branch.startBranch);
-    await deleteBranch(forkPath, branch.temporaryBranch);
+    await discardTemporarySyncBranch(forkPath, branch);
     return { status: "noop" };
   }
   return { status: "staged", branch };
@@ -5112,15 +5257,15 @@ 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} \u2014 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 sync\`:`));
     if (merged.output) console.info(colors_default.dim(indentLines(merged.output)));
     console.info(colors_default.dim(`  ${newest.url}`));
     return "cancel";
   }
-  console.info(`${colors_default.green("\u2713")} merged #${newest.number}`);
+  console.info(`${checkMark} merged #${newest.number}`);
   await deleteBranch(forkPath, newest.headRefName);
   for (const pr of superseded) {
-    console.info(colors_default.dim(`closing #${pr.number} \u2014 its changes are included in #${newest.number}...`));
+    console.info(colors_default.dim(`closing #${pr.number}: its changes are included in #${newest.number}...`));
     closePr(forkPath, pr.number);
     await deleteBranch(forkPath, pr.headRefName);
   }
@@ -5185,15 +5330,20 @@ commit them first (\`git commit --amend --no-edit\` or a new commit).`
   const outcome = await runSyncCycle(config);
   console.info();
   if (outcome.status === "noop") {
-    console.info(colors_default.green("already up to date with upstream \u2014 nothing to sync."));
+    if (outcome.behind) {
+      console.info(colors_default.green("nothing to sync: the last sync 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."));
+    }
     return;
   }
   const { temporaryBranch } = outcome.branch;
   if (outcome.status === "conflicts") {
     console.info(`${warningMark} ${colors_default.yellow(`conflicts on '${temporaryBranch}'. Resolve and stage them, then:`)}`);
-    printFinishSteps();
+    console.info(colors_default.dim("  pnpm cella sync"));
     console.info(colors_default.dim("  rerun commits the sync and stops for drift triage; a further rerun ships (push + PR)."));
-    console.info(colors_default.dim("  let the rerun commit \u2014 a manual `git commit` records a merge commit that bloats the PR."));
+    console.info(colors_default.dim("  let the rerun commit: a manual `git commit` records a merge commit that bloats the PR."));
     return;
   }
   await commitSyncMerge(config, temporaryBranch);
@@ -5201,12 +5351,11 @@ commit them first (\`git commit --amend --no-edit\` or a new commit).`
 
 // src/services/forks.ts
 async function gatherForkStatus(forkPath) {
-  const [branch, porcelain, syncRef] = await Promise.all([
+  const [branch, dirty, syncRef] = await Promise.all([
     getCurrentBranch(forkPath).catch(() => "unknown"),
-    git(["status", "--porcelain"], forkPath, { ignoreErrors: true }),
+    getWorkingTreeChangeCount(forkPath).catch(() => 0),
     getStoredSyncRef(forkPath)
   ]);
-  const dirty = porcelain ? porcelain.split("\n").filter(Boolean).length : 0;
   let lastSync = null;
   if (syncRef) {
     const commitInfo = await getCommitInfo(forkPath, syncRef).catch(() => null);
@@ -5269,7 +5418,8 @@ async function syncFork(config, fork, forkPath) {
     list: false,
     json: false,
     verbose: config.verbose,
-    hard: config.hard
+    hard: config.hard,
+    keepConfig: config.keepConfig
   };
   await runSyncCommand(forkRuntimeConfig);
 }
@@ -5282,8 +5432,7 @@ async function runForks(config) {
   if (config.fork) {
     const match = forks.find((f) => f.name === config.fork);
     if (!match) {
-      console.error(colors_default.red(`fork '${config.fork}' not found in config`));
-      return;
+      throw new Error(`fork '${config.fork}' not found in config`);
     }
     const resolvedPath = resolve7(await resolveForkBasePath(config.forkPath), match.localPath);
     await syncFork(config, match, resolvedPath);
@@ -5292,7 +5441,7 @@ async function runForks(config) {
   const forkBasePath = await resolveForkBasePath(config.forkPath);
   while (true) {
     const choices = await buildForkChoices(forks, forkBasePath);
-    const forkChoices = [...choices, new Separator2("\u2500".repeat(40)), { value: "_exit", name: colors_default.dim("exit") }];
+    const forkChoices = [...choices, new Separator2(MENU_DIVIDER), { value: "_exit", name: colors_default.dim("exit") }];
     const selectedPath = await select4({
       message: "select fork to sync:",
       choices: forkChoices,
@@ -5314,15 +5463,15 @@ async function runForks(config) {
 
 // src/services/stats.ts
 import { readFile as readFile3 } from "fs/promises";
-import { join as join20 } from "path";
+import { join as join18 } from "path";
 
 // src/utils/coverage-utils.ts
-import { spawnSync as spawnSync4 } from "child_process";
-import * as fs3 from "fs";
-import * as path3 from "path";
+import { spawnSync as spawnSync5 } from "child_process";
+import { existsSync as existsSync12, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
+import { join as join17, relative as relative3, sep as sep2 } from "path";
 var STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1e3;
 function summaryPath(forkPath) {
-  return path3.join(forkPath, ".coverage", "coverage-summary.json");
+  return join17(forkPath, ".coverage", "coverage-summary.json");
 }
 function colorPct(pct) {
   if (typeof pct !== "number" || !Number.isFinite(pct)) return colors_default.dim("n/a");
@@ -5341,7 +5490,7 @@ function formatAge(ms) {
 }
 function refreshCoverage(forkPath) {
   console.info(colors_default.dim("running `pnpm test` (this spins up Docker and runs the full suite)..."));
-  const result = spawnSync4("pnpm", ["test"], { cwd: forkPath, stdio: "inherit" });
+  const result = spawnSync5("pnpm", ["test"], { cwd: forkPath, stdio: "inherit" });
   return result.status === 0;
 }
 function printCoverageSummary(forkPath, options = {}) {
@@ -5349,24 +5498,24 @@ function printCoverageSummary(forkPath, options = {}) {
   if (options.refresh) {
     const ok = refreshCoverage(forkPath);
     if (!ok) {
-      console.info(colors_default.red("coverage run failed \u2014 showing last cached results (if any)"));
+      console.info(colors_default.red("coverage run failed: showing last cached results (if any)"));
     }
     console.info();
   }
-  if (!fs3.existsSync(file)) {
+  if (!existsSync12(file)) {
     console.info(colors_default.bold("coverage"));
-    console.info(colors_default.yellow("  no coverage data found \u2014 run `pnpm test` to generate it"));
+    console.info(colors_default.yellow("  no coverage data found: run `pnpm test` to generate it"));
     console.info();
     return;
   }
   let summary;
   let mtimeMs;
   try {
-    summary = JSON.parse(fs3.readFileSync(file, "utf-8"));
-    mtimeMs = fs3.statSync(file).mtimeMs;
+    summary = JSON.parse(readFileSync6(file, "utf8"));
+    mtimeMs = statSync2(file).mtimeMs;
   } catch {
     console.info(colors_default.bold("coverage"));
-    console.info(colors_default.yellow("  could not read coverage-summary.json \u2014 run `pnpm test` to regenerate"));
+    console.info(colors_default.yellow("  could not read coverage-summary.json: run `pnpm test` to regenerate"));
     console.info();
     return;
   }
@@ -5375,9 +5524,9 @@ function printCoverageSummary(forkPath, options = {}) {
   const perPackage = /* @__PURE__ */ new Map();
   for (const [key, entry] of Object.entries(summary)) {
     if (key === "total") continue;
-    const rel = path3.relative(forkPath, key);
+    const rel = relative3(forkPath, key);
     if (rel.startsWith("..")) continue;
-    const pkg = rel.split(path3.sep)[0];
+    const pkg = rel.split(sep2)[0];
     const acc = perPackage.get(pkg) ?? { covered: 0, total: 0 };
     acc.covered += entry.lines.covered;
     acc.total += entry.lines.total;
@@ -5386,10 +5535,10 @@ function printCoverageSummary(forkPath, options = {}) {
   const ageLabel = formatAge(ageMs);
   console.info(colors_default.bold("coverage"), colors_default.dim(`(updated ${ageLabel})`));
   if (stale) {
-    console.info(colors_default.yellow("  \u26A0 data is older than 7 days \u2014 run `pnpm test` to refresh"));
+    console.info(colors_default.yellow("  \u26A0 data is older than 7 days: run `pnpm test` to refresh"));
   }
   if (!Object.keys(summary).some((key) => key !== "total")) {
-    console.info(colors_default.yellow("  no coverage data found \u2014 run `pnpm test` to regenerate"));
+    console.info(colors_default.yellow("  no coverage data found: run `pnpm test` to regenerate"));
     console.info();
     return;
   }
@@ -5408,7 +5557,7 @@ function printCoverageSummary(forkPath, options = {}) {
 // src/services/stats.ts
 var sourceExtensions = /* @__PURE__ */ new Set(["ts", "tsx", "js", "jsx", "mjs", "cjs", "json", "jsonc", "css", "html"]);
 async function getWorkspacePackages(forkPath) {
-  const content = await readFile3(join20(forkPath, "pnpm-workspace.yaml"), "utf-8");
+  const content = await readFile3(join18(forkPath, "pnpm-workspace.yaml"), "utf8");
   return parseYamlBlockList(content, "packages").map((pattern) => {
     if (pattern.endsWith("/*")) {
       const base = pattern.slice(0, -2);
@@ -5472,12 +5621,12 @@ async function collectStats(forkPath) {
   const categories = emptyCat();
   const pkgStats = /* @__PURE__ */ new Map();
   let totalLoc = 0;
-  for (const { path: path4, loc } of entries) {
-    const category = classifyFile(path4);
+  for (const { path, loc } of entries) {
+    const category = classifyFile(path);
     categories[category].files++;
     categories[category].loc += loc;
     totalLoc += loc;
-    const pkg = matchPackage(path4, packages);
+    const pkg = matchPackage(path, packages);
     let entry = pkgStats.get(pkg);
     if (!entry) {
       entry = { total: 0, loc: 0, categories: emptyCat() };
@@ -5554,17 +5703,237 @@ function printStats(stats, verbose) {
   }
   console.info();
 }
-async function runStats(forkPath, options = {}) {
+async function runStats(config) {
+  const { forkPath } = config;
   createSpinner("counting files...");
   const stats = await collectStats(forkPath);
-  spinnerSuccess("Finished counting by raw line of code");
-  if (options.json) {
-    console.info(JSON.stringify(stats, null, 2));
-  } else {
-    printStats(stats, options.verbose ?? false);
+  spinnerSuccess("counted raw lines of code");
+  printStats(stats, config.verbose);
+  console.info();
+  printCoverageSummary(forkPath, { refresh: config.coverage });
+}
+
+// src/services/stats-since.ts
+var kindLabels = {
+  source: "source",
+  test: "tests",
+  stories: "stories",
+  generated: "generated",
+  json: "json",
+  docs: "docs",
+  other: "other"
+};
+var docExtensions = /* @__PURE__ */ new Set(["md", "mdx"]);
+var lockFiles = /* @__PURE__ */ new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lock", "bun.lockb"]);
+var codeExtensions = [...sourceExtensions].filter((ext) => !ext.startsWith("json"));
+function classifyChange(filePath) {
+  const name = filePath.slice(filePath.lastIndexOf("/") + 1);
+  if (lockFiles.has(name)) return "generated";
+  const category = classifyFile(filePath);
+  if (category !== "other") return category;
+  const ext = name.includes(".") ? name.slice(name.lastIndexOf(".") + 1) : "";
+  if (docExtensions.has(ext)) return "docs";
+  return sourceExtensions.has(ext) ? "source" : "other";
+}
+function classifyLine(text) {
+  const line = text.trim();
+  if (!line) return "blank";
+  if (line.startsWith("//") || line.startsWith("/*") || line.startsWith("*") || line.startsWith("{/*")) {
+    return "comments";
+  }
+  return "code";
+}
+function parseNumstat(output) {
+  const files = [];
+  for (const record of output.split("\0")) {
+    if (!record) continue;
+    const [added, removed, ...rest] = record.split("	");
+    const path = rest.join("	");
+    if (!path) continue;
+    files.push({
+      path,
+      kind: classifyChange(path),
+      added: Number.parseInt(added, 10) || 0,
+      removed: Number.parseInt(removed, 10) || 0
+    });
+  }
+  return files;
+}
+function countLineContent(patch, isCounted) {
+  const content = {
+    code: { added: 0, removed: 0 },
+    comments: { added: 0, removed: 0 },
+    blank: { added: 0, removed: 0 }
+  };
+  let counted = false;
+  let remaining = 0;
+  for (const line of patch.split("\n")) {
+    if (remaining > 0) {
+      if (line.startsWith("\\")) continue;
+      remaining--;
+      if (!counted) continue;
+      const change = line.startsWith("+") ? "added" : "removed";
+      content[classifyLine(line.slice(1))][change]++;
+      continue;
+    }
+    if (line.startsWith("diff --git ")) {
+      counted = false;
+      continue;
+    }
+    if (line.startsWith("--- a/") || line.startsWith("+++ b/")) {
+      counted = isCounted(line.slice(6));
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/.exec(line);
+    if (hunk) remaining = Number(hunk[1] ?? 1) + Number(hunk[2] ?? 1);
+  }
+  return content;
+}
+async function collectBranchStats(forkPath, since) {
+  const sinceSha = await git(["rev-parse", "--verify", "--quiet", `${since}^{commit}`], forkPath, {
+    ignoreErrors: true
+  });
+  if (!sinceSha) throw new Error(`unknown ref '${since}'. pass a branch, tag or commit, such as origin/main`);
+  const mergeBase = await git(["merge-base", sinceSha, "HEAD"], forkPath, { ignoreErrors: true });
+  if (!mergeBase) throw new Error(`the current branch shares no history with '${since}'`);
+  const range = [mergeBase, "HEAD"];
+  const files = parseNumstat(await git(["diff", "--numstat", "-z", "--no-renames", ...range], forkPath));
+  const kindOf = new Map(files.map((file) => [file.path, file.kind]));
+  const emptyKind = () => ({ files: 0, added: 0, removed: 0 });
+  const kinds = {
+    source: emptyKind(),
+    test: emptyKind(),
+    stories: emptyKind(),
+    generated: emptyKind(),
+    json: emptyKind(),
+    docs: emptyKind(),
+    other: emptyKind()
+  };
+  const total = emptyKind();
+  const packages = await getWorkspacePackages(forkPath).catch(() => []);
+  const byPackage = /* @__PURE__ */ new Map();
+  const add = (target, file) => {
+    target.files++;
+    target.added += file.added;
+    target.removed += file.removed;
+  };
+  for (const file of files) {
+    add(total, file);
+    add(kinds[file.kind], file);
+    if (file.kind !== "source") continue;
+    const pkg = matchPackage(file.path, packages);
+    const entry = byPackage.get(pkg) ?? emptyKind();
+    add(entry, file);
+    byPackage.set(pkg, entry);
+  }
+  const patch = await git(
+    ["diff", "-U0", "--no-renames", "--no-color", ...range, "--", ...codeExtensions.map((ext) => `*.${ext}`)],
+    forkPath,
+    { ignoreErrors: true }
+  );
+  const sourceContent = kinds.source.files > 0 && !patch ? null : countLineContent(patch, (path) => kindOf.get(path) === "source");
+  const sourceByPackage = Object.fromEntries(
+    [...byPackage.entries()].sort((a, b) => net(b[1]) - net(a[1]) || a[0].localeCompare(b[0]))
+  );
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], forkPath);
+  const status = await git(["status", "--porcelain"], forkPath, { ignoreErrors: true });
+  return {
+    since,
+    mergeBase: mergeBase.slice(0, 7),
+    head: branch === "HEAD" ? await git(["rev-parse", "--short", "HEAD"], forkPath) : branch,
+    total,
+    kinds,
+    sourceContent,
+    sourceByPackage,
+    files: files.sort((a, b) => net(b) - net(a) || a.path.localeCompare(b.path)),
+    uncommitted: status.split("\n").filter(Boolean).length
+  };
+}
+function net(change) {
+  return change.added - change.removed;
+}
+function signed(n) {
+  return n > 0 ? `+${n}` : String(n);
+}
+function changedKinds(stats) {
+  return Object.entries(stats.kinds).filter(([, change]) => change.files > 0).sort((a, b) => net(b[1]) - net(a[1]));
+}
+function formatNetList(parts) {
+  return parts.filter(([, change]) => change.added > 0 || change.removed > 0).map(([label, change]) => `${label} ${signed(net(change))}`).join(", ");
+}
+function formatMarkdown(stats) {
+  const row = (label, change) => `| ${label} | ${change.files} | ${signed(change.added)} | ${signed(-change.removed)} | ${signed(net(change))} |`;
+  const capitalize = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+  const lines = [
+    "| Kind | Files | Added | Removed | Net |",
+    "| --- | ---: | ---: | ---: | ---: |",
+    ...changedKinds(stats).map(
+      ([kind, change]) => row(kind === "json" ? "JSON" : capitalize(kindLabels[kind]), change)
+    ),
+    `| **Total** | **${stats.total.files}** | **${signed(stats.total.added)}** | **${signed(-stats.total.removed)}** | **${signed(net(stats.total))}** |`
+  ];
+  const notes = [];
+  if (stats.sourceContent) {
+    const content = formatNetList(Object.entries(stats.sourceContent));
+    if (content) notes.push(`Source lines by content: ${content}.`);
+  }
+  const byPackage = formatNetList(Object.entries(stats.sourceByPackage));
+  if (byPackage) notes.push(`Source lines by package: ${byPackage}.`);
+  return notes.length > 0 ? [...lines, "", ...notes].join("\n") : lines.join("\n");
+}
+function printBranchStats(stats, verbose) {
+  const columns = (files, change, label) => `  ${files.padStart(5)} ${signed(change.added).padStart(8)} ${signed(-change.removed).padStart(8)} ${colors_default.cyan(signed(net(change)).padStart(8))}  ${label}`;
+  console.info();
+  console.info(colors_default.dim(`  ${"files".padStart(5)} ${"added".padStart(8)} ${"removed".padStart(8)} ${"net".padStart(8)}`));
+  for (const [kind, change] of changedKinds(stats)) {
+    console.info(columns(String(change.files), change, kindLabels[kind]));
+  }
+  console.info(columns(String(stats.total.files), stats.total, colors_default.bold("total")));
+  if (stats.sourceContent && stats.kinds.source.files > 0) {
+    console.info();
+    console.info(colors_default.dim("  source lines by content"));
+    for (const [content, change] of Object.entries(stats.sourceContent)) {
+      console.info(columns("", change, content));
+    }
+  }
+  const packages = Object.entries(stats.sourceByPackage);
+  if (packages.length > 0) {
     console.info();
-    printCoverageSummary(forkPath, { refresh: options.refreshCoverage });
+    console.info(colors_default.dim("  source lines by package"));
+    for (const [name, change] of packages) {
+      console.info(columns(String(change.files), change, name));
+    }
   }
+  if (verbose) {
+    console.info();
+    console.info(DIVIDER);
+    console.info();
+    for (const file of stats.files) {
+      console.info(columns("", file, `${file.path}  ${colors_default.dim(kindLabels[file.kind])}`));
+    }
+  }
+  if (stats.uncommitted > 0) {
+    console.info();
+    console.info(
+      colors_default.dim(`  ${stats.uncommitted} uncommitted file${stats.uncommitted === 1 ? " is" : "s are"} not counted`)
+    );
+  }
+  console.info();
+}
+async function runBranchStats(forkPath, options) {
+  createSpinner("counting changed lines...");
+  const stats = await collectBranchStats(forkPath, options.since);
+  spinnerSuccess(`Counted what ${stats.head} changed since ${stats.since} (${stats.mergeBase})`);
+  if (stats.total.files === 0) {
+    console.info(colors_default.dim(`  nothing committed since ${stats.since}`));
+    return;
+  }
+  if (options.markdown) {
+    writeStdout(formatMarkdown(stats));
+    if (stats.uncommitted > 0) console.info(colors_default.dim(`${stats.uncommitted} uncommitted file(s) are not counted`));
+    return;
+  }
+  printBranchStats(stats, options.verbose ?? false);
 }
 
 // src/cella-cli.ts
@@ -5583,8 +5952,8 @@ function getForkPath() {
   }
   return cwd;
 }
-async function preflight(forkPath) {
-  if (!existsSync13(join21(forkPath, ".git"))) {
+function preflight(forkPath) {
+  if (!existsSync13(join19(forkPath, ".git"))) {
     throw new Error(`not a git repository: ${forkPath}`);
   }
 }
@@ -5602,7 +5971,7 @@ async function main() {
     const userConfig = await loadConfig(forkPath);
     const config = await parseCli(userConfig, forkPath);
     if (!["audit", "forks", "contributions", "stats"].includes(config.service)) {
-      await preflight(forkPath);
+      preflight(forkPath);
     }
     switch (config.service) {
       case "analyze": {
@@ -5613,26 +5982,36 @@ async function main() {
         await runSyncCommand(config);
         break;
       }
-      case "migrate":
+      case "migrate": {
         await runMigrate(config);
         break;
-      case "audit":
-        await runAudit(config, { force: config.force, checkOverrides: config.checkOverrides });
+      }
+      case "audit": {
+        await runAudit(config);
         break;
-      case "forks":
+      }
+      case "forks": {
         await runForks(config);
         break;
-      case "contributions":
+      }
+      case "contributions": {
         await runContributions(config);
         break;
-      case "stats":
-        await runStats(config.forkPath, { verbose: config.verbose, refreshCoverage: config.coverage });
+      }
+      case "stats": {
+        if (config.md && !config.since) throw new Error("--md goes with --since <ref>");
+        if (config.since) {
+          await runBranchStats(config.forkPath, { since: config.since, markdown: config.md, verbose: config.verbose });
+        } else {
+          await runStats(config);
+        }
         break;
+      }
     }
     console.info();
   } catch (error) {
     console.error();
-    console.error(`${colors_default.red("\u2717")} ${error instanceof Error ? error.message : "unknown error"}`);
+    console.error(`${colors_default.red("\u2717")} ${errorMessage(error)}`);
     process9.exit(1);
   }
 }