@cellajs/cli 0.2.3 → 0.3.1

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env tsx
 
 // src/cella-cli.ts
-import { existsSync as existsSync11, statSync as statSync3 } from "fs";
-import { join as join18, resolve as resolve6 } from "path";
+import { existsSync as existsSync13, statSync as statSync3 } from "fs";
+import { join as join21, resolve as resolve8 } from "path";
 import process9 from "process";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { join as join5 } from "path";
+import { join as join8 } from "path";
 import process5 from "process";
 import { select } from "@inquirer/prompts";
 import { Command } from "commander";
@@ -220,7 +220,7 @@ import process4 from "process";
 // package.json
 var package_default = {
   name: "@cellajs/cli",
-  version: "0.2.3",
+  version: "0.3.1",
   private: false,
   license: "MIT",
   description: "CLI for managing your monorepo and syncing with upstream Cella.",
@@ -270,25 +270,25 @@ var package_default = {
     prepare: "lefthook install"
   },
   dependencies: {
-    "@inquirer/core": "^11.2.1",
+    "@inquirer/core": "^12.0.3",
     "@inquirer/prompts": "^8.7.2",
-    "@pierre/diffs": "^1.4.3",
+    "@pierre/diffs": "^1.5.1",
     commander: "^15.0.0",
     "ts-morph": "^28.0.0",
     zod: "^4.6.5"
   },
   devDependencies: {
-    "@biomejs/biome": "^2.5.14",
+    "@biomejs/biome": "^2.5.15",
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
-    "@evilmartians/lefthook": "^2.1.14",
-    "@types/node": "26.5.0",
-    "@typescript/native-preview": "7.0.0-dev.20260702.3",
+    "@evilmartians/lefthook": "^2.1.15",
+    "@types/node": "26.6.3",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     rimraf: "^6.1.3",
     tsup: "^8.5.1",
     tsx: "^4.23.15",
-    typescript: "^6.0.3",
-    vitest: "^4.1.11"
+    typescript: "6.0.3",
+    vitest: "^5.0.3"
   },
   publishConfig: {
     access: "public"
@@ -800,415 +800,480 @@ function printFlagWarnings(options) {
 }
 
 // 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";
-import { join as join4 } from "path";
-function isUnderAnyFolder(filePath, folders) {
-  return folders.some((folder) => {
-    const entry = folder.replace(/\/+$/, "");
-    return filePath === entry || filePath.startsWith(`${entry}/`);
+import { mkdir as mkdir2, readdir, rmdir, unlink } from "fs/promises";
+import { dirname as dirname2, join as join5, resolve as resolve3 } from "path";
+import { promisify } from "util";
+
+// src/utils/manifest.ts
+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) {
+  try {
+    const parsed = JSON.parse(await readFile(join4(cwd, MANIFEST_FILE), "utf8"));
+    const commit = parsed?.upstream?.commit;
+    if (typeof commit !== "string" || !/^[0-9a-f]{40}$/i.test(commit)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function readManifestBase(cwd) {
+  const manifest = await readSyncManifest(cwd);
+  return manifest ? manifest.upstream.commit.toLowerCase() : null;
+}
+async function writeSyncManifest(cwd, manifest) {
+  const manifestPath = join4(cwd, MANIFEST_FILE);
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`, "utf8");
+}
+
+// src/utils/git.ts
+var execFileAsync = promisify(execFile);
+function sanitizeCredentials(text) {
+  return text.replace(/https?:\/\/[^@\s]+@/g, (match) => {
+    const protocol = match.startsWith("https") ? "https" : "http";
+    return `${protocol}://***@`;
   });
 }
-function isIgnored(filePath, config) {
-  return isUnderAnyFolder(filePath, config.overrides?.ignored || []);
+async function git(args, cwd, options = {}) {
+  const env = {
+    ...getEnvSnapshot(),
+    ...options.skipEditor ? { GIT_EDITOR: "true" } : {},
+    ...options.env
+  };
+  const maxBuffer = options.maxBuffer ?? 50 * 1024 * 1024;
+  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);
+    }
+    throw error;
+  }
 }
-function isPinned(filePath, config) {
-  if (isManagedFile(filePath)) return true;
-  return isUnderAnyFolder(filePath, config.overrides?.pinned || []);
+async function getCurrentBranch(cwd) {
+  return git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
 }
-function groupIgnoredUpstreamChanges(files, ignored) {
-  const entries = [...new Set(ignored.map((entry) => entry.replace(/\/+$/, "")).filter(Boolean))];
-  const mostSpecificFirst = [...entries].sort((a, b) => b.length - a.length);
-  const groups = /* @__PURE__ */ new Map();
-  for (const file of files) {
-    if (!file.upstreamOnly || isManagedFile(file.path) || isGeneratedFile(file.path)) continue;
-    const entry = mostSpecificFirst.find((candidate) => isUnderAnyFolder(file.path, [candidate]));
-    if (!entry) continue;
-    const group = groups.get(entry) ?? { entry, paths: [], added: 0, deleted: 0 };
-    group.paths.push(file.path);
-    if (!file.existsInFork) group.added++;
-    if (!file.existsInUpstream) group.deleted++;
-    groups.set(entry, group);
+async function switchBranch(cwd, branch) {
+  await git(["switch", branch], cwd);
+}
+async function switchDetached(cwd, ref) {
+  await git(["switch", "--detach", ref], cwd);
+}
+async function createBranchFrom(cwd, branch, startPoint) {
+  await git(["switch", "-c", branch, "--no-track", startPoint], cwd);
+}
+async function branchExists(cwd, branch) {
+  return await git(["rev-parse", "-q", "--verify", `refs/heads/${branch}`], cwd, { ignoreErrors: true }) !== "";
+}
+async function getBranchWorktree(cwd, branch) {
+  const output = await git(["worktree", "list", "--porcelain"], cwd, { ignoreErrors: true });
+  let worktree = null;
+  for (const line of output.split("\n")) {
+    if (line.startsWith("worktree ")) worktree = line.slice("worktree ".length);
+    else if (line === `branch refs/heads/${branch}`) return worktree;
   }
-  for (const group of groups.values()) group.paths.sort();
-  return entries.flatMap((entry) => groups.get(entry) ?? []);
+  return null;
 }
-function isPinnedForSync(filePath, config, unpinned) {
-  if (isManagedFile(filePath)) return true;
-  if (unpinned) return false;
-  return isPinned(filePath, config);
+async function fastForwardBranch(cwd, branch, ref) {
+  await git(["fetch", "--quiet", ".", `${ref}:refs/heads/${branch}`], cwd);
 }
-function hasGlobChars(entry) {
-  return entry.includes("*") || entry.includes("?");
+async function deleteBranch(cwd, branch) {
+  await git(["branch", "-D", branch], cwd, { ignoreErrors: true });
 }
-function validateOverrides(config, forkPath) {
-  const warnings = [];
-  const pinned = config.overrides?.pinned || [];
-  for (const entry of pinned) {
-    if (hasGlobChars(entry)) {
-      warnings.push({
-        type: "pinned-glob",
-        pattern: entry,
-        message: `pin uses glob (not supported, use a path or folder): ${entry}`
-      });
-    } else if (!existsSync3(join4(forkPath, entry))) {
-      warnings.push({
-        type: "pinned-not-found",
-        pattern: entry,
-        message: `pin not found: ${entry}`
-      });
-    }
+async function pullFastForward(cwd) {
+  await git(["pull", "--ff-only"], cwd, { ignoreErrors: true, skipEditor: true });
+}
+async function getBranchUpstream(cwd, branch = "") {
+  const upstream = await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", `${branch}@{upstream}`], cwd, {
+    ignoreErrors: true
+  });
+  return upstream || null;
+}
+async function getUpstreamStatus(cwd, branch) {
+  const local = branch ? `refs/heads/${branch}` : "HEAD";
+  const upstream = await getBranchUpstream(cwd, branch);
+  if (!upstream) return { upstream: null, ahead: 0, behind: 0 };
+  const remote = upstream.split("/")[0];
+  await git(["fetch", remote], cwd, { ignoreErrors: true, skipEditor: true });
+  const counts = await git(["rev-list", "--left-right", "--count", `${local}...${upstream}`], cwd, {
+    ignoreErrors: true
+  });
+  const [ahead, behind] = counts.split(/\s+/).map((n) => Number.parseInt(n, 10) || 0);
+  return { upstream, ahead: ahead ?? 0, behind: behind ?? 0 };
+}
+async function pushBranch(cwd, remote, branch, options = {}) {
+  await git(["push", "-u", ...options.forceWithLease ? ["--force-with-lease"] : [], remote, branch], cwd);
+}
+async function listBranchMergeCommits(cwd, baseRef) {
+  const out = await git(["rev-list", "--merges", "--first-parent", `${baseRef}..HEAD`], cwd, { ignoreErrors: true });
+  return out ? out.split("\n").filter(Boolean) : [];
+}
+async function flattenBranch(cwd, baseRef, message) {
+  const parent = await getMergeBase(cwd, baseRef, "HEAD");
+  const tree = await git(["rev-parse", "HEAD^{tree}"], cwd);
+  const commit = await git(["commit-tree", tree, "-p", parent, "-m", message], cwd);
+  await git(["reset", "--hard", commit], cwd);
+}
+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 ignored = config.overrides?.ignored || [];
-  for (const entry of ignored) {
-    if (hasGlobChars(entry)) {
-      warnings.push({
-        type: "ignored-not-found",
-        pattern: entry,
-        message: `ignored entry uses glob (not supported, use a path or folder): ${entry}`
-      });
-    } else if (!existsSync3(join4(forkPath, entry.replace(/\/+$/, "")))) {
-      warnings.push({
-        type: "ignored-not-found",
-        pattern: entry,
-        message: `ignored entry not found: ${entry}`
-      });
-    }
+  await git(["commit", "-m", message], cwd, { skipEditor: true });
+}
+async function gitPath(cwd, file) {
+  return resolve3(cwd, await git(["rev-parse", "--git-path", file], cwd));
+}
+async function stageAll(cwd) {
+  await git(["add", "-A"], cwd);
+}
+async function mergeInProgress(cwd) {
+  return await git(["rev-parse", "-q", "--verify", "MERGE_HEAD"], cwd, { ignoreErrors: true }) !== "";
+}
+async function getShortSha(cwd, ref) {
+  return git(["rev-parse", "--short", ref], cwd);
+}
+async function getWorkingTreeChangeCount(cwd) {
+  const status = await git(["status", "--porcelain"], cwd);
+  if (!status) return 0;
+  return status.split("\n").filter(Boolean).length;
+}
+async function remoteExists(cwd, remoteName) {
+  const remotes = await git(["remote"], cwd);
+  return remotes.split("\n").includes(remoteName);
+}
+async function ensureRemote(cwd, remoteName, url) {
+  if (await remoteExists(cwd, remoteName)) {
+    await git(["remote", "set-url", remoteName, url], cwd);
+  } else {
+    await git(["remote", "add", remoteName, url], cwd);
   }
-  return warnings;
 }
-function printWarnings(warnings) {
-  for (const warning of warnings) {
-    console.info(`${warningMark} ${warning.message}`);
+async function fetch2(cwd, remoteName) {
+  await git(["fetch", remoteName], cwd);
+}
+async function fetchUpstreamTags(cwd, remoteName) {
+  await git(["fetch", remoteName, "--no-tags", `+refs/tags/*:refs/${remoteName}/tags/*`], cwd);
+}
+async function resolveLatestReleaseTag(cwd, remoteName) {
+  const prefix = `refs/${remoteName}/tags/`;
+  const output = await git(["for-each-ref", "--sort=-version:refname", "--format=%(refname)", prefix], cwd, {
+    ignoreErrors: true
+  });
+  if (!output) return null;
+  for (const line of output.split("\n")) {
+    const ref = line.trim();
+    if (!ref) continue;
+    const tag = ref.slice(prefix.length);
+    if (/^v\d/.test(tag)) return { tag, ref };
   }
+  return null;
 }
-
-// src/cli.ts
-function readOptions(opts) {
-  const scope = typeof opts.scope === "string" ? opts.scope : void 0;
-  if (scope && scope !== "all" && scope !== "risk" && scope !== "protected") {
-    throw new Error(`invalid --scope '${scope}'. expected one of: all, risk, protected`);
+async function resolveUpstreamCommit(cwd, remoteName, ref) {
+  if (ref.startsWith("-")) return null;
+  const tagRef = `refs/${remoteName}/tags/${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;
+    return { sha, release };
   }
-  const normalizedScope = scope;
-  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,
-    scope: normalizedScope,
-    fork: typeof opts.fork === "string" ? opts.fork : void 0,
-    hard: opts.hard === true,
-    unpinned: opts.unpinned === true,
-    track: opts.track === "release" || opts.track === "branch" ? opts.track : void 0,
-    force: opts.force === true,
-    checkOverrides: opts.checkOverrides === true,
-    coverage: opts.coverage === true,
-    directMerge: opts.directMerge === true
-  };
+  return null;
 }
-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" },
-      { flags: "--list", description: "non-interactive output for tooling (one file per line)" },
-      { flags: "--json", description: "machine-readable output for tooling/agents" },
-      { 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: "--diff <path>", description: "print 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",
-    options: [
-      { flags: "--log", description: "write complete file list to cella-sync.log" },
-      { flags: "--hard", description: "overwrite drifted files with upstream version (aggressive realignment)" },
-      { 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: "--direct-merge",
-        description: "auto-merge (squash) the sync PR once checks pass \u2014 needs auto-merge enabled on the repo"
-      }
+async function isPublishedUpstream(cwd, remoteName, branchRef, sha) {
+  const containing = await git(
+    [
+      "for-each-ref",
+      "--count=1",
+      "--format=%(refname)",
+      "--contains",
+      sha,
+      `refs/remotes/${branchRef}`,
+      `refs/${remoteName}/tags/v*`
     ],
-    includeInMenu: (context) => !context.isUpstreamRepo,
-    menuDescription: () => "merge upstream changes + sync package.json"
-  },
-  {
-    name: "audit",
-    description: "check for outdated packages & vulnerabilities",
-    options: [
-      { flags: "--list", description: "skip interactive update prompts after printing audit results" },
-      { flags: "--force", description: "bypass pnpm metadata cache for fresh registry data" },
-      { flags: "--check-overrides", description: "check which pnpm.overrides are still needed" }
-    ]
-  },
-  {
-    name: "forks",
-    description: "sync downstream to local fork repositories",
-    options: [
-      { flags: "--fork <name>", description: "pre-select fork by name (skips fork selection prompt)" },
-      { 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)" }
-    ],
-    includeInMenu: (context) => context.hasForks
-  },
-  {
-    name: "contributions",
-    description: "pull and adopt changes from 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" }
-    ],
-    includeInMenu: (context) => context.hasForks
-  },
-  {
-    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" }
-    ]
-  }
-];
-async function getMenuContext(userConfig, forkPath) {
-  return {
-    hasForks: (userConfig.forks?.length ?? 0) > 0,
-    isUpstreamRepo: JSON.parse(readFileSync(join5(forkPath, "package.json"), "utf8")).name === "cella"
-  };
+    cwd,
+    { ignoreErrors: true }
+  );
+  return containing !== "";
 }
-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)}`
-  }));
-  return [
-    ...baseChoices,
-    { type: "separator", separator: "\u2500".repeat(40) },
-    { value: "exit", name: colors_default.red(`${label("exit")}${colors_default.dim("quit without doing anything")}`) }
-  ];
+async function getCommitInfo(cwd, ref) {
+  const format = "%H%n%s%n%ar";
+  const output = await git(["log", "-1", `--format=${format}`, ref], cwd);
+  const [hash, message, date] = output.split("\n");
+  return { hash, message, date };
 }
-function addServiceCommand(program, definition, setSelection) {
-  const command = program.command(definition.name).description(definition.description);
-  for (const option of definition.options ?? []) {
-    command.option(option.flags, option.description);
-  }
-  command.action((opts) => {
-    setSelection({
-      service: definition.name,
-      options: readOptions(opts)
-    });
-  });
+async function countCommitsBetween(cwd, fromRef, toRef) {
+  const output = await git(["rev-list", "--count", `${fromRef}..${toRef}`], cwd);
+  return Number.parseInt(output.trim(), 10) || 0;
 }
-function buildProgram(setSelection) {
-  const program = new Command(NAME).name("cella").version(VERSION, "-v, --version", "output the current version").usage("[service] [options]").helpOption("-h, --help", "display help for a command").showHelpAfterError().addHelpText(
-    "after",
-    [
-      "",
-      "Examples:",
-      "  $ cella analyze",
-      "  $ cella analyze --json --scope risk",
-      "  $ cella analyze --open-diff frontend/src/routes/index.tsx",
-      "  $ cella sync --hard",
-      "  $ cella sync --unpinned",
-      "  $ cella sync --track branch",
-      "  $ cella sync --direct-merge",
-      "  $ cella audit --check-overrides",
-      "  $ cella contributions --fork raak --json"
-    ].join("\n")
-  );
-  for (const definition of serviceDefinitions) {
-    addServiceCommand(program, definition, setSelection);
+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 output = await git(args, cwd, { ignoreErrors: true });
+  if (!output) return [];
+  const commits = [];
+  for (const line of output.split("\n")) {
+    if (!line) continue;
+    const [hash, message, date] = line.split("");
+    if (!hash || !message || !date) continue;
+    commits.push({ hash, message, date });
   }
-  return program;
-}
-function parseCommandLine(argv) {
-  if (argv.length <= 2) {
-    return { options: readOptions({}) };
+  const normalizedSkip = Math.max(0, skip);
+  const normalizedLimit = typeof limit === "number" && limit > 0 ? limit : void 0;
+  if (normalizedSkip === 0 && normalizedLimit === void 0) {
+    return commits;
   }
-  let selection = { options: readOptions({}) };
-  const program = buildProgram((nextSelection) => {
-    selection = nextSelection;
-  });
-  program.parse(argv);
-  return selection;
+  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);
 }
-async function promptForService(userConfig, forkPath) {
-  const selected = await select({
-    message: "choose a service:",
-    choices: buildServiceChoices(await getMenuContext(userConfig, forkPath)),
-    loop: false
-  });
-  if (selected === "exit") {
-    console.info(colors_default.dim("exiting..."));
-    console.info();
-    process5.exit(0);
+async function getFileChangeInfo(cwd, fromRef, toRef) {
+  const info = /* @__PURE__ */ new Map();
+  try {
+    const output = await git(["log", "--name-only", "--format=%h %ct %ar", `${fromRef}..${toRef}`], cwd, {
+      ignoreErrors: true
+    });
+    if (!output.trim()) return info;
+    const lines = output.split("\n");
+    let currentHash = "";
+    let currentDate = "";
+    let currentTimestamp = 0;
+    for (const line of lines) {
+      if (!line) continue;
+      const match = line.match(/^([a-f0-9]{7,})\s+(\d+)\s+(.+)$/);
+      if (match) {
+        currentHash = match[1];
+        currentTimestamp = Number(match[2]);
+        currentDate = match[3];
+      } else if (currentHash && currentDate && !info.has(line)) {
+        info.set(line, { date: currentDate, hash: currentHash, timestamp: currentTimestamp });
+      }
+    }
+  } catch {
   }
-  console.info();
-  return selected;
+  return info;
 }
-function buildRuntimeConfig(userConfig, forkPath, selection) {
-  const { branchRef } = resolveUpstream(userConfig.settings);
-  return {
-    ...userConfig,
-    forkPath,
-    upstreamRef: branchRef,
-    service: selection.service ?? "analyze",
-    ...selection.options
-  };
+async function isClean(cwd) {
+  const status = await git(["status", "--porcelain"], cwd);
+  return !status;
 }
-async function parseCli(userConfig, forkPath) {
-  const selection = parseCommandLine(process5.argv);
-  if (selection.options.json || selection.options.diff) setJsonMode(true);
-  printHeader();
-  const warnings = validateOverrides(userConfig, forkPath);
-  if (warnings.length > 0) {
-    printWarnings(warnings);
-    console.info();
+async function assertClean(cwd, subject = "working directory") {
+  if (!await isClean(cwd)) {
+    throw new Error(`${subject} has uncommitted changes. please commit or stash before syncing.`);
   }
-  if (!selection.service) {
-    selection.service = await promptForService(userConfig, forkPath);
+}
+async function createWorktree(cwd, worktreePath, commitRef) {
+  await git(["worktree", "add", "--detach", worktreePath, commitRef], cwd);
+}
+async function removeWorktree(cwd, worktreePath) {
+  await git(["worktree", "remove", worktreePath, "--force"], cwd, { ignoreErrors: true });
+  await git(["worktree", "prune"], cwd, { ignoreErrors: true });
+}
+async function listWorktrees(cwd) {
+  const output = await git(["worktree", "list", "--porcelain"], cwd);
+  const lines = output.split("\n");
+  const paths = [];
+  for (const line of lines) {
+    if (line.startsWith("worktree ")) {
+      paths.push(line.slice(9));
+    }
   }
-  return buildRuntimeConfig(userConfig, forkPath, selection);
+  return paths;
 }
-
-// src/services/analyze.ts
-import { basename as basename4 } from "path";
-
-// src/utils/diff.ts
-import { execFileSync } from "child_process";
-import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
-import { tmpdir } from "os";
-import { basename as basename2, join as join6 } 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);
+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");
   try {
-    return execFileSync("git", args, { cwd, maxBuffer: 50 * 1024 * 1024 });
+    await git(args, cwd, { skipEditor: true });
+    return { success: true, conflicts: [] };
   } catch (error) {
-    const stderr = error.stderr?.toString().trim();
-    throw new Error(stderr || `failed to diff ${filePath}`);
+    const conflicts = await getConflictedFiles(cwd);
+    if (conflicts.length > 0) {
+      return { success: false, conflicts };
+    }
+    throw error;
   }
 }
-function escapeHtml(text) {
-  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+async function getConflictedFiles(cwd) {
+  const output = await git(["diff", "--name-only", "--diff-filter=U"], cwd, { ignoreErrors: true });
+  if (!output) return [];
+  return output.split("\n").filter(Boolean);
 }
-async function renderDiffPage(patch, meta) {
-  const { preloadPatchDiff } = await import("@pierre/diffs/ssr");
-  const { prerenderedHTML } = await preloadPatchDiff({
-    patch,
-    options: {
-      diffStyle: "split",
-      themeType: "system",
-      lineDiffType: "word-alt",
-      hunkSeparators: "line-info",
-      overflow: "wrap",
-      disableFileHeader: true
-    }
-  });
-  const title = `${escapeHtml(meta.filePath)} \xB7 ${escapeHtml(meta.srcLabel)} vs ${escapeHtml(meta.dstLabel)}`;
-  const note = meta.note ? `<span class="note">\xB7 ${escapeHtml(meta.note)}</span>` : "";
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${title}</title>
-<style>
-  :root { color-scheme: light dark; }
-  * { box-sizing: border-box; }
-  body {
-    margin: 0;
-    font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
-    background: light-dark(#fafafa, #111);
-    color: light-dark(#111, #eee);
+async function mergeAbort(cwd) {
+  await git(["merge", "--abort"], cwd, { ignoreErrors: true });
+}
+async function fileExistsAtRef(cwd, ref, filePath) {
+  const result = await git(["ls-tree", "--name-only", ref, "--", filePath], cwd, { ignoreErrors: true });
+  return result !== "";
+}
+async function checkoutFromRef(cwd, ref, filePath) {
+  await git(["checkout", ref, "--", filePath], cwd);
+}
+async function restoreWorktreeFromRef(cwd, ref, filePath) {
+  await git(["restore", `--source=${ref}`, "--worktree", "--", filePath], cwd);
+}
+async function getMergeBase(cwd, ref1, ref2) {
+  return git(["merge-base", ref1, ref2], cwd);
+}
+async function getFileChanges(cwd, baseRef, targetRef) {
+  const output = await git(["diff-tree", "-r", "-M90%", "--no-commit-id", baseRef, targetRef], cwd, {
+    ignoreErrors: true
+  });
+  const changes = /* @__PURE__ */ new Map();
+  if (!output) return changes;
+  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(.+)$/);
+    if (renameMatch) {
+      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
+      });
+      continue;
+    }
+    const match = line.match(/^:\d+ \d+ ([a-f0-9]+) ([a-f0-9]+) ([ADMT])\t(.+)$/);
+    if (match) {
+      const [, baseHash, targetHash, status, filePath] = match;
+      changes.set(filePath, {
+        status,
+        baseHash: baseHash === "0".repeat(40) ? null : baseHash,
+        targetHash: targetHash === "0".repeat(40) ? null : targetHash
+      });
+    }
   }
-  header {
-    display: flex; align-items: baseline; gap: 0.75rem; flex-wrap: wrap;
-    padding: 0.9rem 1.25rem;
-    border-bottom: 1px solid light-dark(#e2e2e2, #2a2a2a);
-    position: sticky; top: 0;
-    background: inherit;
+  return changes;
+}
+async function getDiffStat(cwd, fromRef, toRef, paths = []) {
+  const args = ["diff", "--numstat", "--no-renames", fromRef, toRef];
+  if (paths.length > 0) args.push("--", ...paths);
+  const out = await git(args, cwd, { ignoreErrors: true });
+  const stat = /* @__PURE__ */ new Map();
+  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, {
+      additions: a === "-" ? null : Number(a),
+      deletions: d === "-" ? null : Number(d)
+    });
   }
-  header .brand { font-weight: 600; color: light-dark(#0891b2, #22d3ee); }
-  header code { font-family: ui-monospace, monospace; font-size: 0.9rem; }
-  header .sides { margin-left: auto; font-size: 0.8rem; opacity: 0.7; }
-  main { max-width: 1400px; margin: 1rem auto; padding: 0 1rem 2rem; }
-  .diff-shell {
-    border: 1px solid light-dark(#e2e2e2, #2a2a2a);
-    border-radius: 8px; overflow: hidden;
-    background: light-dark(#fff, #161616);
+  return stat;
+}
+async function getFileHashesAtRef(cwd, ref) {
+  const output = await git(["ls-tree", "-r", ref], cwd);
+  const hashes = /* @__PURE__ */ new Map();
+  if (!output) return hashes;
+  for (const line of output.split("\n")) {
+    if (!line) continue;
+    const match = line.match(/^\d+ \w+ ([a-f0-9]+)\t(.+)$/);
+    if (match) {
+      const [, hash, filePath] = match;
+      hashes.set(filePath, hash);
+    }
   }
-</style>
-</head>
-<body>
-<header>
-  <span class="brand">\u29C8 cella diff</span>
-  <code>${escapeHtml(meta.filePath)}</code>
-  <span class="sides">${escapeHtml(meta.srcLabel)} \u2190 \u2192 ${escapeHtml(meta.dstLabel)} ${note}</span>
-</header>
-<main>
-  <!-- Declarative shadow DOM: the library's CSS targets :host, which only
-       matches inside a shadow root (its browser component renders into one). -->
-  <div class="diff-shell">
-    <template shadowrootmode="open">
-${prerenderedHTML}
-    </template>
-  </div>
-</main>
-</body>
-</html>`;
+  return hashes;
 }
-function openWithDefaultApp(target) {
+async function restoreToHead(cwd, filePath) {
+  await git(["checkout", "HEAD", "--", filePath], cwd);
+}
+async function batchRestoreToHead(cwd, filePaths) {
+  if (filePaths.length === 0) return;
+  await git(["checkout", "HEAD", "--", ...filePaths], cwd);
+}
+async function gitRm(cwd, filePath) {
+  await git(["rm", "-f", "--", filePath], cwd, { ignoreErrors: true });
+}
+async function batchGitRm(cwd, filePaths) {
+  if (filePaths.length === 0) return;
+  await git(["rm", "-f", "--", ...filePaths], cwd, { ignoreErrors: true });
+}
+async function getStagedNewFiles(cwd) {
+  const output = await git(["diff", "--cached", "--name-only", "--diff-filter=A"], cwd, { ignoreErrors: true });
+  return output ? output.split("\n").filter(Boolean) : [];
+}
+async function batchUnstageFiles(cwd, filePaths) {
+  if (filePaths.length === 0) return;
+  await git(["rm", "--cached", "-f", "--", ...filePaths], cwd, { ignoreErrors: true });
+}
+async function gitMv(cwd, oldPath, newPath) {
+  const newDir = dirname2(join5(cwd, newPath));
+  await mkdir2(newDir, { recursive: true });
+  await git(["mv", "-f", oldPath, newPath], cwd);
+}
+async function fileExistsInWorktree(cwd, filePath) {
+  return existsSync3(join5(cwd, filePath));
+}
+async function removeFileFromWorktree(cwd, filePath) {
+  const fullPath = join5(cwd, filePath);
   try {
-    if (process6.platform === "win32") {
-      execFileSync("rundll32", ["url.dll,FileProtocolHandler", target], { stdio: "ignore" });
-    } else {
-      execFileSync(process6.platform === "darwin" ? "open" : "xdg-open", [target], { stdio: "ignore" });
+    await unlink(fullPath);
+    await cleanupEmptyParentDirs(cwd, dirname2(filePath));
+  } catch {
+  }
+}
+async function removeFileFully(cwd, filePath) {
+  await gitRm(cwd, filePath);
+  await removeFileFromWorktree(cwd, filePath);
+}
+async function cleanupEmptyParentDirs(cwd, relativePath) {
+  if (!relativePath || relativePath === ".") return;
+  const fullPath = join5(cwd, relativePath);
+  try {
+    const entries = await readdir(fullPath);
+    if (entries.length === 0) {
+      await rmdir(fullPath);
+      await cleanupEmptyParentDirs(cwd, dirname2(relativePath));
     }
   } catch {
   }
 }
-async function openDiffInBrowser(patch, meta, repoPath) {
-  const html = await renderDiffPage(patch, meta);
-  const dir = join6(tmpdir(), `cella-diff-${basename2(repoPath)}`);
-  mkdirSync(dir, { recursive: true });
-  const outPath = join6(dir, `${meta.filePath.replace(/[^\w.-]+/g, "-")}.html`);
-  writeFileSync2(outPath, html);
-  openWithDefaultApp(outPath);
-  return outPath;
+async function storeLastSyncRef(cwd, upstreamHash) {
+  await git(["update-ref", "refs/cella/last-sync", upstreamHash], cwd);
+  const head = await git(["rev-parse", "HEAD"], cwd, { ignoreErrors: true });
+  if (head) {
+    await git(["update-ref", "refs/cella/last-sync-head", head], cwd);
+  }
 }
-
-// src/utils/cleanup.ts
-import { existsSync as existsSync5, rmSync } from "fs";
-import { tmpdir as tmpdir2 } from "os";
-import { basename as basename3, join as join9 } from "path";
-import process7 from "process";
-
-// src/utils/git.ts
-import { execFile } from "child_process";
-import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir2, readdir, rmdir, unlink } from "fs/promises";
-import { dirname as dirname2, join as join8 } from "path";
-import { promisify } from "util";
-
-// src/utils/manifest.ts
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { dirname, join as join7 } from "path";
-var MANIFEST_FILE = "cella/cella.manifest.json";
-async function readSyncManifest(cwd) {
+async function stagePath(cwd, path4) {
+  await git(["add", "--", path4], cwd, { ignoreErrors: true });
+}
+async function getStoredSyncRef(cwd) {
+  const ref = await git(["rev-parse", "refs/cella/last-sync"], cwd, { ignoreErrors: true });
+  return ref || null;
+}
+async function getStoredSyncHead(cwd) {
+  const ref = await git(["rev-parse", "refs/cella/last-sync-head"], cwd, { ignoreErrors: true });
+  return ref || null;
+}
+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(await readFile(join7(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;
@@ -1216,588 +1281,690 @@ async function readSyncManifest(cwd) {
     return null;
   }
 }
-async function readManifestBase(cwd) {
-  const manifest = await readSyncManifest(cwd);
+async function readManifestBaseAtRef(cwd, ref) {
+  const manifest = await readManifestAtRef(cwd, ref);
   return manifest ? manifest.upstream.commit.toLowerCase() : null;
 }
-async function writeSyncManifest(cwd, manifest) {
-  const manifestPath = join7(cwd, MANIFEST_FILE);
-  await mkdir(dirname(manifestPath), { recursive: true });
-  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
-`, "utf8");
-}
-
-// src/utils/git.ts
-var execFileAsync = promisify(execFile);
-function sanitizeCredentials(text) {
-  return text.replace(/https?:\/\/[^@\s]+@/g, (match) => {
-    const protocol = match.startsWith("https") ? "https" : "http";
-    return `${protocol}://***@`;
-  });
+async function readPackageVersionAtRef(cwd, ref) {
+  const raw = await git(["show", `${ref}:package.json`], cwd, { ignoreErrors: true });
+  if (!raw) return null;
+  try {
+    const version = JSON.parse(raw).version;
+    return typeof version === "string" && version ? version : null;
+  } catch {
+    return null;
+  }
 }
-async function git(args, cwd, options = {}) {
-  const env = {
-    ...getEnvSnapshot(),
-    ...options.skipEditor ? { GIT_EDITOR: "true" } : {},
-    ...options.env
-  };
-  const maxBuffer = options.maxBuffer ?? 50 * 1024 * 1024;
+async function commitObjectExists(cwd, sha) {
   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);
-    }
-    throw error;
+    await git(["cat-file", "-e", `${sha}^{commit}`], cwd);
+    return true;
+  } catch {
+    return false;
   }
 }
-async function getCurrentBranch(cwd) {
-  return git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+async function getRootCommit(cwd, ref) {
+  const out = await git(["rev-list", "--max-parents=0", ref], cwd, { ignoreErrors: true });
+  const roots = out.split("\n").filter(Boolean);
+  return roots.length > 0 ? roots[roots.length - 1] : null;
 }
-async function switchBranch(cwd, branch) {
-  await git(["switch", branch], cwd);
+var SCAFFOLD_CANDIDATE_LIMIT = 400;
+var SCAFFOLD_SCORE_CONCURRENCY = 10;
+var SCAFFOLD_MATCH_MAX_DIFF_RATIO = 0.3;
+async function inferScaffoldBase(cwd, headRef, upstreamRef) {
+  const root = await getRootCommit(cwd, headRef);
+  if (!root) return null;
+  const rootDate = await git(["show", "-s", "--format=%cI", root], cwd, { ignoreErrors: true });
+  if (!rootDate) return null;
+  const before = new Date(new Date(rootDate).getTime() + 24 * 60 * 60 * 1e3).toISOString();
+  const revList = await git(
+    ["rev-list", `--max-count=${SCAFFOLD_CANDIDATE_LIMIT}`, `--before=${before}`, upstreamRef],
+    cwd,
+    { ignoreErrors: true }
+  );
+  const candidates = revList.split("\n").filter(Boolean);
+  if (candidates.length === 0) return null;
+  const totalPaths = (await git(["ls-tree", "-r", "--name-only", root], cwd)).split("\n").filter(Boolean).length;
+  if (totalPaths === 0) return null;
+  let best = null;
+  outer: for (let i = 0; i < candidates.length; i += SCAFFOLD_SCORE_CONCURRENCY) {
+    const chunk = candidates.slice(i, i + SCAFFOLD_SCORE_CONCURRENCY);
+    const scores = await Promise.all(
+      chunk.map(async (sha) => {
+        try {
+          const out = await git(["diff-tree", "-r", "--name-only", sha, root], cwd);
+          return { sha, diff: out ? out.split("\n").length : 0 };
+        } catch {
+          return { sha, diff: Number.POSITIVE_INFINITY };
+        }
+      })
+    );
+    for (const score of scores) {
+      if (!best || score.diff < best.diff) best = score;
+      if (best.diff === 0) break outer;
+    }
+  }
+  if (!best || best.diff / totalPaths > SCAFFOLD_MATCH_MAX_DIFF_RATIO) return null;
+  return best.sha;
 }
-async function createBranchFrom(cwd, branch, startPoint) {
-  await git(["switch", "-c", branch, startPoint], cwd);
+async function readRootTrailerBase(cwd, headRef) {
+  const root = await getRootCommit(cwd, headRef);
+  if (!root) return null;
+  const message = await git(["show", "-s", "--format=%B", root], cwd, { ignoreErrors: true });
+  const match = message.match(/^cella-base:\s*([0-9a-f]{40})$/im);
+  return match ? match[1].toLowerCase() : null;
 }
-async function deleteBranch(cwd, branch) {
-  await git(["branch", "-D", branch], cwd, { ignoreErrors: true });
+async function isShallowRepository(cwd) {
+  const out = await git(["rev-parse", "--is-shallow-repository"], cwd, { ignoreErrors: true });
+  return out === "true";
 }
-async function pullFastForward(cwd) {
-  await git(["pull", "--ff-only"], cwd, { ignoreErrors: true, skipEditor: true });
+async function unshallowRepository(cwd) {
+  try {
+    await git(["fetch", "--unshallow"], cwd, { skipEditor: true });
+  } catch (error) {
+    const detail = error instanceof Error ? `
+
+${error.message}` : "";
+    throw new Error(
+      `this is a shallow clone and its full history could not be restored automatically.
+Sync needs the complete history to find the common ancestor with upstream. Restore it with:
+
+  git fetch --unshallow
+
+then re-run sync.${detail}`
+    );
+  }
 }
-async function getUpstreamStatus(cwd) {
-  const upstream = await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], cwd, {
-    ignoreErrors: true
-  });
-  if (!upstream) return { upstream: null, ahead: 0, behind: 0 };
-  const remote = upstream.split("/")[0];
-  await git(["fetch", remote], cwd, { ignoreErrors: true, skipEditor: true });
-  const counts = await git(["rev-list", "--left-right", "--count", `HEAD...${upstream}`], cwd, { ignoreErrors: true });
-  const [ahead, behind] = counts.split(/\s+/).map((n) => Number.parseInt(n, 10) || 0);
-  return { upstream, ahead: ahead ?? 0, behind: behind ?? 0 };
+async function ensureSyncBase(cwd, headRef, upstreamRef) {
+  if (await isShallowRepository(cwd)) {
+    await unshallowRepository(cwd);
+  }
+  const nativeBase = await git(["merge-base", headRef, upstreamRef], cwd, { ignoreErrors: true });
+  if (nativeBase) return;
+  const sources = [
+    () => getStoredSyncRef(cwd),
+    () => readManifestBaseAtRef(cwd, headRef),
+    () => readManifestBase(cwd),
+    () => readRootTrailerBase(cwd, headRef),
+    () => inferScaffoldBase(cwd, headRef, upstreamRef)
+  ];
+  let baseSha = null;
+  for (const source of sources) {
+    const sha = await source();
+    if (sha && await commitObjectExists(cwd, sha)) {
+      baseSha = sha;
+      break;
+    }
+  }
+  if (!baseSha) {
+    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
+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>
+`
+    );
+  }
+  const root = await getRootCommit(cwd, headRef);
+  if (!root) throw new Error("could not determine the fork's root commit to bootstrap sync ancestry");
+  await git(["replace", "-f", "--graft", root, baseSha], cwd);
+  await git(["update-ref", "refs/cella/last-sync", baseSha], cwd);
 }
-async function pushBranch(cwd, remote, branch, options = {}) {
-  await git(["push", "-u", ...options.forceWithLease ? ["--force-with-lease"] : [], remote, branch], cwd);
+async function isAncestor(cwd, ancestor, descendant) {
+  try {
+    await git(["merge-base", "--is-ancestor", ancestor, descendant], cwd);
+    return true;
+  } catch {
+    return false;
+  }
 }
-async function listBranchMergeCommits(cwd, baseRef) {
-  const out = await git(["rev-list", "--merges", "--first-parent", `${baseRef}..HEAD`], cwd, { ignoreErrors: true });
-  return out ? out.split("\n").filter(Boolean) : [];
+async function getLegacySyncRef(cwd, headRef) {
+  const storedRef = await getStoredSyncRef(cwd);
+  if (!storedRef) return null;
+  const storedHead = await getStoredSyncHead(cwd);
+  if (storedHead) {
+    const currentHead = await git(["rev-parse", headRef], cwd, { ignoreErrors: true });
+    if (currentHead && currentHead === storedHead) return null;
+  }
+  return storedRef;
 }
-async function flattenBranch(cwd, baseRef, message) {
-  const parent = await getMergeBase(cwd, baseRef, "HEAD");
-  const tree = await git(["rev-parse", "HEAD^{tree}"], cwd);
-  const commit = await git(["commit-tree", tree, "-p", parent, "-m", message], cwd);
-  await git(["reset", "--hard", commit], cwd);
+async function getEffectiveMergeBase(cwd, headRef, upstreamRef) {
+  const gitBase = await getMergeBase(cwd, headRef, upstreamRef);
+  const recorded = await readManifestBaseAtRef(cwd, headRef) ?? await getLegacySyncRef(cwd, headRef);
+  if (!recorded) {
+    return { base: gitBase, isStale: false, storedRef: null };
+  }
+  const recordedIsNewer = await isAncestor(cwd, gitBase, recorded);
+  if (recordedIsNewer && recorded !== gitBase) {
+    return { base: recorded, isStale: true, storedRef: recorded };
+  }
+  return { base: gitBase, isStale: false, storedRef: recorded };
 }
-async function commitSquash(cwd, message) {
-  for (const file of ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE"]) {
-    const path4 = join8(cwd, ".git", file);
-    if (existsSync4(path4)) await unlink(path4);
+async function withTemporarySyncBaseGraft(cwd, headRef, baseSha, fn) {
+  const headSha = await git(["rev-parse", headRef], cwd, { ignoreErrors: true });
+  if (!headSha || !await commitObjectExists(cwd, baseSha)) return fn();
+  if (await isAncestor(cwd, baseSha, headSha)) return fn();
+  const existingReplacement = await git(["replace", "-l", headSha], cwd, { ignoreErrors: true });
+  if (existingReplacement) return fn();
+  const parentsRaw = await git(["log", "-1", "--format=%P", headSha], cwd, { ignoreErrors: true });
+  const parents = parentsRaw ? parentsRaw.split(/\s+/) : [];
+  await git(["replace", "-f", "--graft", headSha, ...parents, baseSha], cwd);
+  try {
+    return await fn();
+  } finally {
+    await git(["replace", "-d", headSha], cwd, { ignoreErrors: true });
   }
-  await git(["commit", "-m", message], cwd, { skipEditor: true });
 }
-async function stageAll(cwd) {
-  await git(["add", "-A"], cwd);
+
+// src/utils/migration-notes.ts
+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 isUpstreamOnly(filePath) {
+  return filePath === NOTES_DIR || filePath.startsWith(`${NOTES_DIR}/`);
+}
+function bodyLines(lines) {
+  let inComment = false;
+  return lines.filter((line) => {
+    if (!inComment && !line.trimStart().startsWith("<!--")) return true;
+    inComment = !line.includes("-->");
+    return false;
+  });
 }
-function mergeInProgress(cwd) {
-  return existsSync4(join8(cwd, ".git", "MERGE_HEAD"));
+function parseNote(id, source, fileNames) {
+  const lines = source.replace(/\r\n/g, "\n").split("\n");
+  const close = lines[0] === "---" ? lines.indexOf("---", 1) : -1;
+  const meta = /* @__PURE__ */ new Map();
+  for (const line of lines.slice(1, Math.max(close, 1))) {
+    const match = /^(\w+):\s*(.*)$/.exec(line);
+    if (match) meta.set(match[1], match[2].trim());
+  }
+  const body = bodyLines(lines.slice(close + 1)).join("\n");
+  const blocks = body.split(/\n\s*\n/).map((block) => block.trim()).filter(Boolean);
+  const title = /^# (.+)$/.exec(blocks[0] ?? "")?.[1].trim();
+  const summary = title && blocks[1] && !/^(#|>|[-*|]|```)/.test(blocks[1]) ? blocks[1].replace(/\s*\n\s*/g, " ") : "";
+  return {
+    id,
+    title: title || id,
+    summary,
+    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
+  };
 }
-async function getShortSha(cwd, ref) {
-  return git(["rev-parse", "--short", ref], cwd);
+async function listNoteIds(cwd, ref) {
+  const out = await git(["ls-tree", "--name-only", `${ref}:${NOTES_DIR}`], cwd, { ignoreErrors: true });
+  return out.split("\n").filter((name) => NOTE_ID.test(name)).sort();
+}
+async function readNote(cwd, ref, id) {
+  const source = await git(["show", `${ref}:${NOTES_DIR}/${id}/README.md`], cwd, { ignoreErrors: true });
+  if (!source) return null;
+  const files = await git(["ls-tree", "--name-only", `${ref}:${NOTES_DIR}/${id}`], cwd, { ignoreErrors: true });
+  return parseNote(id, source, files.split("\n").filter(Boolean));
+}
+async function arrivedNoteIds(cwd, from, to) {
+  const [before, after] = await Promise.all([listNoteIds(cwd, from), listNoteIds(cwd, to)]);
+  const known = new Set(before);
+  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"));
+  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 pending = [...new Set(ids)].sort();
+  if (pending.length === 0) {
+    await rm(path4, { force: true });
+    return;
+  }
+  await mkdir3(dirname3(path4), { recursive: true });
+  await writeFile2(path4, `${JSON.stringify({ pending }, null, 2)}
+`, "utf8");
 }
-async function getWorkingTreeChangeCount(cwd) {
-  const status = await git(["status", "--porcelain"], cwd);
-  if (!status) return 0;
-  return status.split("\n").filter(Boolean).length;
+function noteUrl(upstreamGitHubUrl, commit, id) {
+  return upstreamGitHubUrl ? `${upstreamGitHubUrl}/blob/${commit}/${NOTES_DIR}/${id}/README.md` : void 0;
 }
-async function remoteExists(cwd, remoteName) {
-  const remotes = await git(["remote"], cwd);
-  return remotes.split("\n").includes(remoteName);
+function formatNotesLine(total, open, arrived, options = {}) {
+  const parts = [open === 0 ? `all ${total} handled` : `${Math.max(0, total - open)} of ${total} handled`];
+  if (arrived) parts.push(`${arrived} ${options.dryRun ? "arrive" : "arrived"} with this sync`);
+  if (open > 0) parts.push(`${open} open: pnpm cella migrate`);
+  return `migration notes: ${parts.join(" \xB7 ")}`;
 }
-async function ensureRemote(cwd, remoteName, url) {
-  if (await remoteExists(cwd, remoteName)) {
-    await git(["remote", "set-url", remoteName, url], cwd);
-  } else {
-    await git(["remote", "add", remoteName, url], cwd);
-  }
+
+// src/utils/overrides.ts
+function isUnderAnyFolder(filePath, folders) {
+  return folders.some((folder) => {
+    const entry = folder.replace(/\/+$/, "");
+    return filePath === entry || filePath.startsWith(`${entry}/`);
+  });
 }
-async function fetch2(cwd, remoteName) {
-  await git(["fetch", remoteName], cwd);
+function isIgnored(filePath, config) {
+  return isUpstreamOnly(filePath) || isUnderAnyFolder(filePath, config.overrides?.ignored || []);
 }
-async function fetchUpstreamTags(cwd, remoteName) {
-  await git(["fetch", remoteName, "--no-tags", `+refs/tags/*:refs/${remoteName}/tags/*`], cwd);
+function isPinned(filePath, config) {
+  if (isManagedFile(filePath)) return true;
+  return isUnderAnyFolder(filePath, config.overrides?.pinned || []);
 }
-async function resolveLatestReleaseTag(cwd, remoteName) {
-  const prefix = `refs/${remoteName}/tags/`;
-  const output = await git(["for-each-ref", "--sort=-version:refname", "--format=%(refname)", prefix], cwd, {
-    ignoreErrors: true
-  });
-  if (!output) return null;
-  for (const line of output.split("\n")) {
-    const ref = line.trim();
-    if (!ref) continue;
-    const tag = ref.slice(prefix.length);
-    if (/^v\d/.test(tag)) return { tag, ref };
+function groupIgnoredUpstreamChanges(files, ignored) {
+  const entries = [...new Set(ignored.map((entry) => entry.replace(/\/+$/, "")).filter(Boolean))];
+  const mostSpecificFirst = [...entries].sort((a, b) => b.length - a.length);
+  const groups = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    if (!file.upstreamOnly || isManagedFile(file.path) || isGeneratedFile(file.path)) continue;
+    const entry = mostSpecificFirst.find((candidate) => isUnderAnyFolder(file.path, [candidate]));
+    if (!entry) continue;
+    const group = groups.get(entry) ?? { entry, paths: [], added: 0, deleted: 0 };
+    group.paths.push(file.path);
+    if (!file.existsInFork) group.added++;
+    if (!file.existsInUpstream) group.deleted++;
+    groups.set(entry, group);
   }
-  return null;
+  for (const group of groups.values()) group.paths.sort();
+  return entries.flatMap((entry) => groups.get(entry) ?? []);
 }
-async function getCommitInfo(cwd, ref) {
-  const format = "%H%n%s%n%ar";
-  const output = await git(["log", "-1", `--format=${format}`, ref], cwd);
-  const [hash, message, date] = output.split("\n");
-  return { hash, message, date };
+function isPinnedForSync(filePath, config, unpinned) {
+  if (isManagedFile(filePath)) return true;
+  if (unpinned) return false;
+  return isPinned(filePath, config);
 }
-async function countCommitsBetween(cwd, fromRef, toRef) {
-  const output = await git(["rev-list", "--count", `${fromRef}..${toRef}`], cwd);
-  return Number.parseInt(output.trim(), 10) || 0;
+function hasGlobChars(entry) {
+  return entry.includes("*") || entry.includes("?");
 }
-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 output = await git(args, cwd, { ignoreErrors: true });
-  if (!output) return [];
-  const commits = [];
-  for (const line of output.split("\n")) {
-    if (!line) continue;
-    const [hash, message, date] = line.split("");
-    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);
-}
-async function getFileChangeInfo(cwd, fromRef, toRef) {
-  const info = /* @__PURE__ */ new Map();
-  try {
-    const output = await git(["log", "--name-only", "--format=%h %ct %ar", `${fromRef}..${toRef}`], cwd, {
-      ignoreErrors: true
-    });
-    if (!output.trim()) return info;
-    const lines = output.split("\n");
-    let currentHash = "";
-    let currentDate = "";
-    let currentTimestamp = 0;
-    for (const line of lines) {
-      if (!line) continue;
-      const match = line.match(/^([a-f0-9]{7,})\s+(\d+)\s+(.+)$/);
-      if (match) {
-        currentHash = match[1];
-        currentTimestamp = Number(match[2]);
-        currentDate = match[3];
-      } else if (currentHash && currentDate && !info.has(line)) {
-        info.set(line, { date: currentDate, hash: currentHash, timestamp: currentTimestamp });
-      }
-    }
-  } catch {
-  }
-  return info;
-}
-async function isClean(cwd) {
-  const status = await git(["status", "--porcelain"], cwd);
-  return !status;
-}
-async function assertClean(cwd, subject = "working directory") {
-  if (!await isClean(cwd)) {
-    throw new Error(`${subject} has uncommitted changes. please commit or stash before syncing.`);
-  }
-}
-async function createWorktree(cwd, worktreePath, commitRef) {
-  await git(["worktree", "add", "--detach", worktreePath, commitRef], cwd);
-}
-async function removeWorktree(cwd, worktreePath) {
-  await git(["worktree", "remove", worktreePath, "--force"], cwd, { ignoreErrors: true });
-  await git(["worktree", "prune"], cwd, { ignoreErrors: true });
-}
-async function listWorktrees(cwd) {
-  const output = await git(["worktree", "list", "--porcelain"], cwd);
-  const lines = output.split("\n");
-  const paths = [];
-  for (const line of lines) {
-    if (line.startsWith("worktree ")) {
-      paths.push(line.slice(9));
-    }
-  }
-  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");
-  try {
-    await git(args, cwd, { skipEditor: true });
-    return { success: true, conflicts: [] };
-  } catch (error) {
-    const conflicts = await getConflictedFiles(cwd);
-    if (conflicts.length > 0) {
-      return { success: false, conflicts };
-    }
-    throw error;
-  }
-}
-async function getConflictedFiles(cwd) {
-  const output = await git(["diff", "--name-only", "--diff-filter=U"], cwd, { ignoreErrors: true });
-  if (!output) return [];
-  return output.split("\n").filter(Boolean);
-}
-async function mergeAbort(cwd) {
-  await git(["merge", "--abort"], cwd, { ignoreErrors: true });
-}
-async function fileExistsAtRef(cwd, ref, filePath) {
-  const result = await git(["ls-tree", "--name-only", ref, "--", filePath], cwd, { ignoreErrors: true });
-  return result !== "";
-}
-async function checkoutFromRef(cwd, ref, filePath) {
-  await git(["checkout", ref, "--", filePath], cwd);
-}
-async function restoreWorktreeFromRef(cwd, ref, filePath) {
-  await git(["restore", `--source=${ref}`, "--worktree", "--", filePath], cwd);
-}
-async function getMergeBase(cwd, ref1, ref2) {
-  return git(["merge-base", ref1, ref2], cwd);
-}
-async function getFileChanges(cwd, baseRef, targetRef) {
-  const output = await git(["diff-tree", "-r", "-M90%", "--no-commit-id", baseRef, targetRef], cwd, {
-    ignoreErrors: true
-  });
-  const changes = /* @__PURE__ */ new Map();
-  if (!output) return changes;
-  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(.+)$/);
-    if (renameMatch) {
-      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
+function validateOverrides(config, forkPath) {
+  const warnings = [];
+  const pinned = config.overrides?.pinned || [];
+  for (const entry of pinned) {
+    if (hasGlobChars(entry)) {
+      warnings.push({
+        type: "pinned-glob",
+        pattern: entry,
+        message: `pin uses glob (not supported, use a path or folder): ${entry}`
       });
-      continue;
-    }
-    const match = line.match(/^:\d+ \d+ ([a-f0-9]+) ([a-f0-9]+) ([ADMT])\t(.+)$/);
-    if (match) {
-      const [, baseHash, targetHash, status, filePath] = match;
-      changes.set(filePath, {
-        status,
-        baseHash: baseHash === "0".repeat(40) ? null : baseHash,
-        targetHash: targetHash === "0".repeat(40) ? null : targetHash
+    } else if (!existsSync5(join7(forkPath, entry))) {
+      warnings.push({
+        type: "pinned-not-found",
+        pattern: entry,
+        message: `pin not found: ${entry}`
       });
     }
   }
-  return changes;
-}
-async function getDiffStat(cwd, fromRef, toRef, paths = []) {
-  const args = ["diff", "--numstat", "--no-renames", fromRef, toRef];
-  if (paths.length > 0) args.push("--", ...paths);
-  const out = await git(args, cwd, { ignoreErrors: true });
-  const stat = /* @__PURE__ */ new Map();
-  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, {
-      additions: a === "-" ? null : Number(a),
-      deletions: d === "-" ? null : Number(d)
-    });
-  }
-  return stat;
-}
-async function getFileHashesAtRef(cwd, ref) {
-  const output = await git(["ls-tree", "-r", ref], cwd);
-  const hashes = /* @__PURE__ */ new Map();
-  if (!output) return hashes;
-  for (const line of output.split("\n")) {
-    if (!line) continue;
-    const match = line.match(/^\d+ \w+ ([a-f0-9]+)\t(.+)$/);
-    if (match) {
-      const [, hash, filePath] = match;
-      hashes.set(filePath, hash);
+  const ignored = config.overrides?.ignored || [];
+  for (const entry of ignored) {
+    if (hasGlobChars(entry)) {
+      warnings.push({
+        type: "ignored-not-found",
+        pattern: entry,
+        message: `ignored entry uses glob (not supported, use a path or folder): ${entry}`
+      });
+    } else if (!existsSync5(join7(forkPath, entry.replace(/\/+$/, "")))) {
+      warnings.push({
+        type: "ignored-not-found",
+        pattern: entry,
+        message: `ignored entry not found: ${entry}`
+      });
     }
   }
-  return hashes;
-}
-async function restoreToHead(cwd, filePath) {
-  await git(["checkout", "HEAD", "--", filePath], cwd);
-}
-async function batchRestoreToHead(cwd, filePaths) {
-  if (filePaths.length === 0) return;
-  await git(["checkout", "HEAD", "--", ...filePaths], cwd);
-}
-async function gitRm(cwd, filePath) {
-  await git(["rm", "-f", "--", filePath], cwd, { ignoreErrors: true });
-}
-async function batchGitRm(cwd, filePaths) {
-  if (filePaths.length === 0) return;
-  await git(["rm", "-f", "--", ...filePaths], cwd, { ignoreErrors: true });
-}
-async function getStagedNewFiles(cwd) {
-  const output = await git(["diff", "--cached", "--name-only", "--diff-filter=A"], cwd, { ignoreErrors: true });
-  return output ? output.split("\n").filter(Boolean) : [];
-}
-async function batchUnstageFiles(cwd, filePaths) {
-  if (filePaths.length === 0) return;
-  await git(["rm", "--cached", "-f", "--", ...filePaths], cwd, { ignoreErrors: true });
-}
-async function gitMv(cwd, oldPath, newPath) {
-  const newDir = dirname2(join8(cwd, newPath));
-  await mkdir2(newDir, { recursive: true });
-  await git(["mv", "-f", oldPath, newPath], cwd);
-}
-async function fileExistsInWorktree(cwd, filePath) {
-  return existsSync4(join8(cwd, filePath));
+  return warnings;
 }
-async function removeFileFromWorktree(cwd, filePath) {
-  const fullPath = join8(cwd, filePath);
-  try {
-    await unlink(fullPath);
-    await cleanupEmptyParentDirs(cwd, dirname2(filePath));
-  } catch {
+function printWarnings(warnings) {
+  for (const warning of warnings) {
+    console.info(`${warningMark} ${warning.message}`);
   }
 }
-async function removeFileFully(cwd, filePath) {
-  await gitRm(cwd, filePath);
-  await removeFileFromWorktree(cwd, filePath);
-}
-async function cleanupEmptyParentDirs(cwd, relativePath) {
-  if (!relativePath || relativePath === ".") return;
-  const fullPath = join8(cwd, relativePath);
-  try {
-    const entries = await readdir(fullPath);
-    if (entries.length === 0) {
-      await rmdir(fullPath);
-      await cleanupEmptyParentDirs(cwd, dirname2(relativePath));
-    }
-  } catch {
+
+// src/cli.ts
+function readOptions(opts) {
+  const scope = typeof opts.scope === "string" ? opts.scope : void 0;
+  if (scope && scope !== "all" && scope !== "risk" && scope !== "protected") {
+    throw new Error(`invalid --scope '${scope}'. expected one of: all, risk, protected`);
   }
+  const normalizedScope = scope;
+  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,
+    scope: normalizedScope,
+    fork: typeof opts.fork === "string" ? opts.fork : void 0,
+    hard: opts.hard === true,
+    unpinned: opts.unpinned === true,
+    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,
+    mark: Array.isArray(opts.mark) ? opts.mark.filter((id) => typeof id === "string") : void 0
+  };
 }
-async function storeLastSyncRef(cwd, upstreamHash) {
-  await git(["update-ref", "refs/cella/last-sync", upstreamHash], cwd);
-  const head = await git(["rev-parse", "HEAD"], cwd, { ignoreErrors: true });
-  if (head) {
-    await git(["update-ref", "refs/cella/last-sync-head", head], cwd);
+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" },
+      { flags: "--list", description: "non-interactive output for tooling (one file per line)" },
+      { flags: "--json", description: "machine-readable output for tooling/agents" },
+      { 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" },
+      { 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",
+    options: [
+      { flags: "--log", description: "write complete file list to cella-sync.log" },
+      { flags: "--hard", description: "overwrite drifted files with upstream version (aggressive realignment)" },
+      { 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" }
+    ],
+    includeInMenu: (context) => !context.isUpstreamRepo,
+    menuDescription: () => "merge upstream changes + sync package.json"
+  },
+  {
+    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" },
+      { 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: "--mark <ids...>", description: "record notes as handled" }
+    ],
+    includeInMenu: (context) => !context.isUpstreamRepo
+  },
+  {
+    name: "audit",
+    description: "check for outdated packages & vulnerabilities",
+    options: [
+      { flags: "--list", description: "skip interactive update prompts after printing audit results" },
+      { flags: "--force", description: "bypass pnpm metadata cache for fresh registry data" },
+      { flags: "--check-overrides", description: "check which pnpm.overrides are still needed" }
+    ]
+  },
+  {
+    name: "forks",
+    description: "sync downstream to local fork repositories",
+    options: [
+      { flags: "--fork <name>", description: "pre-select fork by name (skips fork selection prompt)" },
+      { 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)" }
+    ],
+    includeInMenu: (context) => context.hasForks
+  },
+  {
+    name: "contributions",
+    description: "pull and adopt changes from 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" }
+    ],
+    includeInMenu: (context) => context.hasForks
+  },
+  {
+    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" }
+    ]
   }
+];
+async function getMenuContext(userConfig, forkPath) {
+  return {
+    hasForks: (userConfig.forks?.length ?? 0) > 0,
+    isUpstreamRepo: JSON.parse(readFileSync(join8(forkPath, "package.json"), "utf8")).name === "cella"
+  };
 }
-async function stagePath(cwd, path4) {
-  await git(["add", "--", path4], cwd, { ignoreErrors: true });
-}
-async function getStoredSyncRef(cwd) {
-  const ref = await git(["rev-parse", "refs/cella/last-sync"], cwd, { ignoreErrors: true });
-  return ref || null;
-}
-async function getStoredSyncHead(cwd) {
-  const ref = await git(["rev-parse", "refs/cella/last-sync-head"], cwd, { ignoreErrors: true });
-  return ref || null;
+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)}`
+  }));
+  return [
+    ...baseChoices,
+    { type: "separator", separator: "\u2500".repeat(40) },
+    { value: "exit", name: colors_default.red(`${label("exit")}${colors_default.dim("quit without doing anything")}`) }
+  ];
 }
-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;
+function addServiceCommand(program, definition, setSelection) {
+  const command = program.command(definition.name).description(definition.description);
+  for (const option of definition.options ?? []) {
+    command.option(option.flags, option.description);
   }
+  command.action((opts) => {
+    setSelection({
+      service: definition.name,
+      options: readOptions(opts)
+    });
+  });
 }
-async function readManifestBaseAtRef(cwd, ref) {
-  const manifest = await readManifestAtRef(cwd, ref);
-  return manifest ? manifest.upstream.commit.toLowerCase() : null;
-}
-async function readPackageVersionAtRef(cwd, ref) {
-  const raw = await git(["show", `${ref}:package.json`], cwd, { ignoreErrors: true });
-  if (!raw) return null;
-  try {
-    const version = JSON.parse(raw).version;
-    return typeof version === "string" && version ? version : null;
-  } catch {
-    return null;
+function buildProgram(setSelection) {
+  const program = new Command(NAME).name("cella").version(VERSION, "-v, --version", "output the current version").usage("[service] [options]").helpOption("-h, --help", "display help for a command").showHelpAfterError().addHelpText(
+    "after",
+    [
+      "",
+      "Examples:",
+      "  $ cella analyze",
+      "  $ cella analyze --json --scope risk",
+      "  $ cella analyze --open-diff frontend/src/routes/index.tsx",
+      "  $ cella sync --hard",
+      "  $ cella sync --unpinned",
+      "  $ cella sync --track branch",
+      "  $ cella sync --ref 4f7d87c",
+      "  $ cella migrate --mark 20261002T0614-config-switch",
+      "  $ cella audit --check-overrides",
+      "  $ cella contributions --fork raak --json"
+    ].join("\n")
+  );
+  for (const definition of serviceDefinitions) {
+    addServiceCommand(program, definition, setSelection);
   }
+  return program;
 }
-async function commitObjectExists(cwd, sha) {
-  try {
-    await git(["cat-file", "-e", `${sha}^{commit}`], cwd);
-    return true;
-  } catch {
-    return false;
+function parseCommandLine(argv) {
+  if (argv.length <= 2) {
+    return { options: readOptions({}) };
   }
+  let selection = { options: readOptions({}) };
+  const program = buildProgram((nextSelection) => {
+    selection = nextSelection;
+  });
+  program.parse(argv);
+  return selection;
 }
-async function getRootCommit(cwd, ref) {
-  const out = await git(["rev-list", "--max-parents=0", ref], cwd, { ignoreErrors: true });
-  const roots = out.split("\n").filter(Boolean);
-  return roots.length > 0 ? roots[roots.length - 1] : null;
-}
-var SCAFFOLD_CANDIDATE_LIMIT = 400;
-var SCAFFOLD_SCORE_CONCURRENCY = 10;
-var SCAFFOLD_MATCH_MAX_DIFF_RATIO = 0.3;
-async function inferScaffoldBase(cwd, headRef, upstreamRef) {
-  const root = await getRootCommit(cwd, headRef);
-  if (!root) return null;
-  const rootDate = await git(["show", "-s", "--format=%cI", root], cwd, { ignoreErrors: true });
-  if (!rootDate) return null;
-  const before = new Date(new Date(rootDate).getTime() + 24 * 60 * 60 * 1e3).toISOString();
-  const revList = await git(
-    ["rev-list", `--max-count=${SCAFFOLD_CANDIDATE_LIMIT}`, `--before=${before}`, upstreamRef],
-    cwd,
-    { ignoreErrors: true }
-  );
-  const candidates = revList.split("\n").filter(Boolean);
-  if (candidates.length === 0) return null;
-  const totalPaths = (await git(["ls-tree", "-r", "--name-only", root], cwd)).split("\n").filter(Boolean).length;
-  if (totalPaths === 0) return null;
-  let best = null;
-  outer: for (let i = 0; i < candidates.length; i += SCAFFOLD_SCORE_CONCURRENCY) {
-    const chunk = candidates.slice(i, i + SCAFFOLD_SCORE_CONCURRENCY);
-    const scores = await Promise.all(
-      chunk.map(async (sha) => {
-        try {
-          const out = await git(["diff-tree", "-r", "--name-only", sha, root], cwd);
-          return { sha, diff: out ? out.split("\n").length : 0 };
-        } catch {
-          return { sha, diff: Number.POSITIVE_INFINITY };
-        }
-      })
-    );
-    for (const score of scores) {
-      if (!best || score.diff < best.diff) best = score;
-      if (best.diff === 0) break outer;
-    }
+async function promptForService(userConfig, forkPath) {
+  const selected = await select({
+    message: "choose a service:",
+    choices: buildServiceChoices(await getMenuContext(userConfig, forkPath)),
+    loop: false
+  });
+  if (selected === "exit") {
+    console.info(colors_default.dim("exiting..."));
+    console.info();
+    process5.exit(0);
   }
-  if (!best || best.diff / totalPaths > SCAFFOLD_MATCH_MAX_DIFF_RATIO) return null;
-  return best.sha;
-}
-async function readRootTrailerBase(cwd, headRef) {
-  const root = await getRootCommit(cwd, headRef);
-  if (!root) return null;
-  const message = await git(["show", "-s", "--format=%B", root], cwd, { ignoreErrors: true });
-  const match = message.match(/^cella-base:\s*([0-9a-f]{40})$/im);
-  return match ? match[1].toLowerCase() : null;
-}
-async function isShallowRepository(cwd) {
-  const out = await git(["rev-parse", "--is-shallow-repository"], cwd, { ignoreErrors: true });
-  return out === "true";
+  console.info();
+  return selected;
 }
-async function unshallowRepository(cwd) {
-  try {
-    await git(["fetch", "--unshallow"], cwd, { skipEditor: true });
-  } catch (error) {
-    const detail = error instanceof Error ? `
-
-${error.message}` : "";
-    throw new Error(
-      `this is a shallow clone and its full history could not be restored automatically.
-Sync needs the complete history to find the common ancestor with upstream. Restore it with:
-
-  git fetch --unshallow
-
-then re-run sync.${detail}`
-    );
-  }
+function buildRuntimeConfig(userConfig, forkPath, selection) {
+  const { branchRef } = resolveUpstream(userConfig.settings);
+  return {
+    ...userConfig,
+    forkPath,
+    upstreamRef: branchRef,
+    service: selection.service ?? "analyze",
+    ...selection.options
+  };
 }
-async function ensureSyncBase(cwd, headRef, upstreamRef) {
-  if (await isShallowRepository(cwd)) {
-    await unshallowRepository(cwd);
+async function parseCli(userConfig, forkPath) {
+  const selection = parseCommandLine(process5.argv);
+  if (selection.options.json || selection.options.diff) setJsonMode(true);
+  printHeader();
+  const warnings = validateOverrides(userConfig, forkPath);
+  if (warnings.length > 0) {
+    printWarnings(warnings);
+    console.info();
   }
-  const nativeBase = await git(["merge-base", headRef, upstreamRef], cwd, { ignoreErrors: true });
-  if (nativeBase) return;
-  const sources = [
-    () => getStoredSyncRef(cwd),
-    () => readManifestBaseAtRef(cwd, headRef),
-    () => readManifestBase(cwd),
-    () => readRootTrailerBase(cwd, headRef),
-    () => inferScaffoldBase(cwd, headRef, upstreamRef)
-  ];
-  let baseSha = null;
-  for (const source of sources) {
-    const sha = await source();
-    if (sha && await commitObjectExists(cwd, sha)) {
-      baseSha = sha;
-      break;
-    }
+  if (!selection.service) {
+    selection.service = await promptForService(userConfig, forkPath);
   }
-  if (!baseSha) {
-    throw new Error(
-      `no common ancestor between the fork and '${upstreamRef}', and no sync base could be determined.
+  return buildRuntimeConfig(userConfig, forkPath, selection);
+}
 
-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
-upstream. Seed it manually with the upstream commit the fork was created from, then re-run sync:
+// src/services/analyze.ts
+import { basename as basename4 } from "path";
 
-  git update-ref refs/cella/last-sync <upstream-sha>
-`
-    );
-  }
-  const root = await getRootCommit(cwd, headRef);
-  if (!root) throw new Error("could not determine the fork's root commit to bootstrap sync ancestry");
-  await git(["replace", "-f", "--graft", root, baseSha], cwd);
-  await git(["update-ref", "refs/cella/last-sync", baseSha], cwd);
-}
-async function isAncestor(cwd, ancestor, descendant) {
-  try {
-    await git(["merge-base", "--is-ancestor", ancestor, descendant], cwd);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function getLegacySyncRef(cwd, headRef) {
-  const storedRef = await getStoredSyncRef(cwd);
-  if (!storedRef) return null;
-  const storedHead = await getStoredSyncHead(cwd);
-  if (storedHead) {
-    const currentHead = await git(["rev-parse", headRef], cwd, { ignoreErrors: true });
-    if (currentHead && currentHead === storedHead) return null;
+// src/utils/diff.ts
+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 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 });
+  } catch (error) {
+    const stderr = error.stderr?.toString().trim();
+    throw new Error(stderr || `failed to diff ${filePath}`);
   }
-  return storedRef;
 }
-async function getEffectiveMergeBase(cwd, headRef, upstreamRef) {
-  const gitBase = await getMergeBase(cwd, headRef, upstreamRef);
-  const recorded = await readManifestBaseAtRef(cwd, headRef) ?? await getLegacySyncRef(cwd, headRef);
-  if (!recorded) {
-    return { base: gitBase, isStale: false, storedRef: null };
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+async function renderDiffPage(patch, meta) {
+  const { preloadPatchDiff } = await import("@pierre/diffs/ssr");
+  const { prerenderedHTML } = await preloadPatchDiff({
+    patch,
+    options: {
+      diffStyle: "split",
+      themeType: "system",
+      lineDiffType: "word-alt",
+      hunkSeparators: "line-info",
+      overflow: "wrap",
+      disableFileHeader: true
+    }
+  });
+  const title = `${escapeHtml(meta.filePath)} \xB7 ${escapeHtml(meta.srcLabel)} vs ${escapeHtml(meta.dstLabel)}`;
+  const note = meta.note ? `<span class="note">\xB7 ${escapeHtml(meta.note)}</span>` : "";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+    background: light-dark(#fafafa, #111);
+    color: light-dark(#111, #eee);
   }
-  const recordedIsNewer = await isAncestor(cwd, gitBase, recorded);
-  if (recordedIsNewer && recorded !== gitBase) {
-    return { base: recorded, isStale: true, storedRef: recorded };
+  header {
+    display: flex; align-items: baseline; gap: 0.75rem; flex-wrap: wrap;
+    padding: 0.9rem 1.25rem;
+    border-bottom: 1px solid light-dark(#e2e2e2, #2a2a2a);
+    position: sticky; top: 0;
+    background: inherit;
   }
-  return { base: gitBase, isStale: false, storedRef: recorded };
+  header .brand { font-weight: 600; color: light-dark(#0891b2, #22d3ee); }
+  header code { font-family: ui-monospace, monospace; font-size: 0.9rem; }
+  header .sides { margin-left: auto; font-size: 0.8rem; opacity: 0.7; }
+  main { max-width: 1400px; margin: 1rem auto; padding: 0 1rem 2rem; }
+  .diff-shell {
+    border: 1px solid light-dark(#e2e2e2, #2a2a2a);
+    border-radius: 8px; overflow: hidden;
+    background: light-dark(#fff, #161616);
+  }
+</style>
+</head>
+<body>
+<header>
+  <span class="brand">\u29C8 cella diff</span>
+  <code>${escapeHtml(meta.filePath)}</code>
+  <span class="sides">${escapeHtml(meta.srcLabel)} \u2190 \u2192 ${escapeHtml(meta.dstLabel)} ${note}</span>
+</header>
+<main>
+  <!-- Declarative shadow DOM: the library's CSS targets :host, which only
+       matches inside a shadow root (its browser component renders into one). -->
+  <div class="diff-shell">
+    <template shadowrootmode="open">
+${prerenderedHTML}
+    </template>
+  </div>
+</main>
+</body>
+</html>`;
 }
-async function withTemporarySyncBaseGraft(cwd, headRef, baseSha, fn) {
-  const headSha = await git(["rev-parse", headRef], cwd, { ignoreErrors: true });
-  if (!headSha || !await commitObjectExists(cwd, baseSha)) return fn();
-  if (await isAncestor(cwd, baseSha, headSha)) return fn();
-  const existingReplacement = await git(["replace", "-l", headSha], cwd, { ignoreErrors: true });
-  if (existingReplacement) return fn();
-  const parentsRaw = await git(["log", "-1", "--format=%P", headSha], cwd, { ignoreErrors: true });
-  const parents = parentsRaw ? parentsRaw.split(/\s+/) : [];
-  await git(["replace", "-f", "--graft", headSha, ...parents, baseSha], cwd);
+function openWithDefaultApp(target) {
   try {
-    return await fn();
-  } finally {
-    await git(["replace", "-d", headSha], cwd, { ignoreErrors: true });
+    if (process6.platform === "win32") {
+      execFileSync("rundll32", ["url.dll,FileProtocolHandler", target], { stdio: "ignore" });
+    } else {
+      execFileSync(process6.platform === "darwin" ? "open" : "xdg-open", [target], { stdio: "ignore" });
+    }
+  } catch {
   }
 }
+async function openDiffInBrowser(patch, meta, repoPath) {
+  const html = await renderDiffPage(patch, meta);
+  const dir = join9(tmpdir(), `cella-diff-${basename2(repoPath)}`);
+  mkdirSync(dir, { recursive: true });
+  const outPath = join9(dir, `${meta.filePath.replace(/[^\w.-]+/g, "-")}.html`);
+  writeFileSync2(outPath, html);
+  openWithDefaultApp(outPath);
+  return outPath;
+}
+
+// src/services/merge-engine.ts
+import { existsSync as existsSync7 } from "fs";
+import { rm as rm2 } from "fs/promises";
+import { join as join11 } 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 process7 from "process";
 var WORKTREE_PREFIXES = {
   sync: "cella-sync-",
   view: "cella-view-"
 };
 function buildWorktreePath(kind, repoPath) {
-  return join9(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}`);
+  const key = createHash("sha256").update(resolve4(repoPath)).digest("hex").slice(0, 8);
+  return join10(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}-${key}`);
+}
+function legacyWorktreePath(kind, repoPath) {
+  return join10(tmpdir2(), `${WORKTREE_PREFIXES[kind]}${basename3(repoPath)}`);
 }
 function getWorktreePath(repoPath) {
   return buildWorktreePath("sync", repoPath);
@@ -1815,22 +1982,21 @@ function unregisterWorktree() {
 }
 async function cleanupWorktree(repoPath, worktreePath) {
   await removeWorktree(repoPath, worktreePath);
-  if (existsSync5(worktreePath)) {
+  if (existsSync6(worktreePath)) {
     rmSync(worktreePath, { recursive: true, force: true });
   }
   unregisterWorktree();
 }
 async function cleanupLeftoverWorktrees(repoPath) {
   for (const kind of Object.keys(WORKTREE_PREFIXES)) {
-    const worktreePath = buildWorktreePath(kind, repoPath);
-    if (existsSync5(worktreePath)) {
-      await cleanupWorktree(repoPath, worktreePath);
+    for (const worktreePath of [buildWorktreePath(kind, repoPath), legacyWorktreePath(kind, repoPath)]) {
+      if (existsSync6(worktreePath)) await cleanupWorktree(repoPath, worktreePath);
     }
   }
   const prefixes = Object.values(WORKTREE_PREFIXES);
   const worktrees = await listWorktrees(repoPath);
   for (const wt of worktrees) {
-    if (prefixes.some((prefix) => wt.includes(prefix)) && !existsSync5(wt)) {
+    if (prefixes.some((prefix) => wt.includes(prefix)) && !existsSync6(wt)) {
       await removeWorktree(repoPath, wt);
     }
   }
@@ -1861,6 +2027,51 @@ function registerSignalHandlers() {
   cleanupRegistered = true;
 }
 
+// src/utils/versions.ts
+function parseComparableVersion(version) {
+  const trimmed = version.trim();
+  if (trimmed === "" || trimmed === "*" || trimmed.includes("workspace:") || trimmed.includes("catalog:") || trimmed.includes("file:") || trimmed.includes("link:") || trimmed.includes("git+") || trimmed.includes("github:") || trimmed.includes("http://") || trimmed.includes("https://") || trimmed.includes("||")) {
+    return null;
+  }
+  const match = trimmed.match(
+    /^(?:\^|~|>=|<=|>|<|=)?\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2] ?? 0),
+    patch: Number(match[3] ?? 0)
+  };
+}
+function compareVersions(left, right) {
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  return left.patch - right.patch;
+}
+
+// src/utils/cli-version.ts
+var CLI_PACKAGE = "@cellajs/cli";
+async function readUpstreamCliRange(repoPath, ref) {
+  const source = await git(["show", `${ref}:package.json`], repoPath, { ignoreErrors: true });
+  if (!source) return null;
+  try {
+    const pkg = JSON.parse(source);
+    return pkg.devDependencies?.[CLI_PACKAGE] ?? pkg.dependencies?.[CLI_PACKAGE] ?? null;
+  } catch {
+    return null;
+  }
+}
+function cliVersionMismatch(running, range) {
+  if (/^\s*(<|>(?!=))/.test(range)) return null;
+  const required = parseComparableVersion(range);
+  const current = parseComparableVersion(running);
+  if (!required || !current || compareVersions(current, required) >= 0) return null;
+  return [
+    `upstream needs ${CLI_PACKAGE} ${range}, this is ${running}: an older CLI misses fixes to the sync itself.`,
+    `  update it, commit, then rerun: pnpm add -D -w '${CLI_PACKAGE}@${range}'`
+  ].join("\n");
+}
+
 // src/utils/upstream-overrides.ts
 import { Node, Project as Project2, SyntaxKind as SyntaxKind2 } from "ts-morph";
 var LIST_KEYS = ["pinned", "ignored"];
@@ -2359,6 +2570,20 @@ function formatLocalCheckoutDetail(forkPath, branch, headSha, changeCount, upstr
   const workingTree = changeCount === 0 ? "  working tree clean" : `  ${changeCount} uncommitted change${changeCount === 1 ? "" : "s"} in working tree, not included in analysis`;
   return [`${forkPath}`, `  ${branch} @ ${headSha}${tracking}`, workingTree].join("\n");
 }
+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}.`
+    );
+  }
+  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.`
+    );
+  }
+  return resolved.release ? { ref: resolved.release.ref, releaseTag: resolved.release.tag } : { ref: resolved.sha };
+}
 async function prepareUpstream(config, onProgress, onStep) {
   const { forkPath } = config;
   onProgress?.("checking local checkout...");
@@ -2378,7 +2603,12 @@ async function prepareUpstream(config, onProgress, onStep) {
   await fetch2(forkPath, remoteName);
   let upstreamRef = branchRef;
   let releaseTag;
-  if (track === "release") {
+  if (config.ref) {
+    await fetchUpstreamTags(forkPath, remoteName);
+    const pinned = await resolvePinnedRef(forkPath, config, remoteName, branchRef, config.ref);
+    upstreamRef = pinned.ref;
+    releaseTag = pinned.releaseTag;
+  } else if (track === "release") {
     await fetchUpstreamTags(forkPath, remoteName);
     const latest = await resolveLatestReleaseTag(forkPath, remoteName);
     if (!latest) {
@@ -2389,14 +2619,30 @@ async function prepareUpstream(config, onProgress, onStep) {
     upstreamRef = latest.ref;
     releaseTag = latest.tag;
   }
+  const upstreamLabel = releaseTag ?? (config.ref ? `--ref ${config.ref}` : upstreamRef);
   config.upstreamRef = upstreamRef;
-  onStep?.("remote configured", `${releaseTag ?? upstreamRef} \u2192 ${config.settings.upstreamUrl}`);
+  onStep?.("remote configured", `${upstreamLabel} \u2192 ${config.settings.upstreamUrl}`);
+  const cliRange = await readUpstreamCliRange(forkPath, upstreamRef);
+  const cliMismatch = cliRange ? cliVersionMismatch(VERSION, cliRange) : null;
+  if (cliMismatch) throw new Error(cliMismatch);
   onProgress?.("checking sync base...");
   await ensureSyncBase(forkPath, "HEAD", upstreamRef);
   const upstreamGitHubUrl = getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0;
   const aggressive = config.hard === true || config.unpinned === true;
-  const mergeBase = aggressive ? await getMergeBase(forkPath, "HEAD", upstreamRef) : (await getEffectiveMergeBase(forkPath, "HEAD", upstreamRef)).base;
+  const syncPoint = (await getEffectiveMergeBase(forkPath, "HEAD", upstreamRef)).base;
+  const mergeBase = aggressive ? await getMergeBase(forkPath, "HEAD", upstreamRef) : syncPoint;
   const upstreamCommit = await getCommitInfo(forkPath, upstreamRef);
+  if (upstreamCommit.hash !== syncPoint && await isAncestor(forkPath, upstreamCommit.hash, syncPoint)) {
+    const [upstreamShort, syncShort] = await Promise.all([
+      getShortSha(forkPath, upstreamCommit.hash),
+      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(
+      `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;
@@ -2436,9 +2682,34 @@ async function upstreamOnlyReports(config, ctx, files) {
     return {};
   }
 }
+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)
+    ]);
+    return { total: total.length, arrived, pending: [.../* @__PURE__ */ new Set([...pending, ...arrived])] };
+  } catch {
+    return void 0;
+  }
+}
+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;
+  await git(["rm", "-r", "-q", "--ignore-unmatch", "--", NOTES_DIR], forkPath);
+  await rm2(join11(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;
+  const notes = await readNotesInRange(config, ctx);
   const { remainingConflicts, analyzedFiles, autoMergedFiles, protectedConflicts } = await applyDirectMerge(
     forkPath,
     upstreamRef,
@@ -2465,6 +2736,11 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
     await storeLastSyncRef(forkPath, upstreamCommit.hash);
     await writeSyncManifest(forkPath, syncManifest);
     await stagePath(forkPath, MANIFEST_FILE);
+    if (notes) {
+      await writePending(forkPath, notes.pending);
+      await stagePath(forkPath, PENDING_FILE);
+    }
+    await removeUpstreamOnlyCopy(forkPath, onStep);
   };
   if (remainingConflicts.length > 0) {
     await recordSyncPoint();
@@ -2488,12 +2764,14 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
     autoMergedFiles,
     protectedConflicts,
     ...resultMeta(config, ctx),
-    ...await upstreamOnlyReports(config, ctx, analyzedFiles)
+    ...await upstreamOnlyReports(config, ctx, analyzedFiles),
+    ...notesResult(notes)
   };
 }
 async function runAnalyzePreview(config, ctx, onProgress, onStep) {
   const { forkPath } = config;
   const worktreePath = getWorktreePath(forkPath);
+  const notes = await readNotesInRange(config, ctx);
   onProgress?.("creating worktree in temp directory...");
   await createWorktree(forkPath, worktreePath, "HEAD");
   onStep?.("worktree created", worktreePath);
@@ -2527,7 +2805,8 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
     conflicts: analyzedFiles.filter((f) => f.status === "diverged").map((f) => f.path),
     protectedConflicts: analyzedFiles.filter((f) => f.upstreamChanged).map((f) => f.path),
     ...resultMeta(config, ctx),
-    ...reports
+    ...reports,
+    ...notesResult(notes)
   };
 }
 async function runMergeEngine(config, options) {
@@ -2545,6 +2824,151 @@ async function runMergeEngine(config, options) {
   }
 }
 
+// src/services/migrate.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { mkdir as mkdir4, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname4, join as join12 } from "path";
+var EXTRACT_DIR = "node_modules/.cache/cella/migrations";
+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}'`);
+  }
+  return ref;
+}
+async function readNotesStatus(config) {
+  try {
+    const ref = await resolveNotesRef(config);
+    if (!ref) return null;
+    const [ids, pending] = await Promise.all([listNoteIds(config.forkPath, ref), readPending(config.forkPath, ref)]);
+    return ids.length > 0 || pending.length > 0 ? { total: ids.length, open: pending.length } : null;
+  } catch {
+    return null;
+  }
+}
+async function printMigrationNotesLine(config, result) {
+  const notes = result?.migrationNotes;
+  if (notes) {
+    if (notes.total === 0) return;
+    console.info();
+    console.info(
+      colors_default.dim(formatNotesLine(notes.total, notes.open, notes.arrived.length, { dryRun: config.service === "analyze" }))
+    );
+    return;
+  }
+  const status = await readNotesStatus(config);
+  if (!status) return;
+  console.info();
+  console.info(colors_default.dim(formatNotesLine(status.total, status.open)));
+}
+function toJson(note, url, open) {
+  return { ...note, kind: note.codemod ? "codemod" : "manual", open, url: url ?? null };
+}
+function printNote(index, note, url) {
+  const tags = [
+    note.codemod ? "codemod" : "manual",
+    note.syncBreaking ? "sync-breaking" : null,
+    note.clientCacheBump ? "cache-bump" : null
+  ].filter(Boolean).join(", ");
+  console.info(`${index}. ${note.title}  ${colors_default.dim(`[${tags}]`)}`);
+  console.info(colors_default.dim(`   id:      ${note.id}`));
+  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}`));
+  console.info();
+}
+async function extractNote(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);
+  for (const file of files) {
+    const content = execFileSync2("git", ["show", `${ref}:${NOTES_DIR}/${id}/${file}`], {
+      cwd: forkPath,
+      maxBuffer: 50 * 1024 * 1024
+    });
+    const path4 = join12(forkPath, target, file);
+    await mkdir4(dirname4(path4), { recursive: true });
+    await writeFile3(path4, content);
+  }
+  console.info(`${colors_default.green("\u2713")} 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(" ")}`));
+}
+async function markNotes(config, ref, pending, ids) {
+  const open = new Set(pending);
+  const unknown = ids.filter((id) => !open.has(id));
+  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 (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)));
+}
+async function runMigrate(config) {
+  const { forkPath } = config;
+  const ref = await resolveNotesRef(config);
+  if (!ref) {
+    console.info(colors_default.dim("no sync point recorded yet: migration notes start with the first `pnpm cella sync`."));
+    return;
+  }
+  const pending = await readPending(forkPath, ref);
+  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.extract) return extractNote(config, ref, config.extract);
+  if (config.show) {
+    const source = await git(["show", `${ref}:${NOTES_DIR}/${config.show}/README.md`], forkPath, {
+      ignoreErrors: true
+    });
+    if (!source) throw new Error(`no migration note '${config.show}' at upstream ${ref.slice(0, 7)}`);
+    const url = urlOf(config.show);
+    if (url) console.info(colors_default.dim(url));
+    console.info(source);
+    return;
+  }
+  const ids = config.all ? await listNoteIds(forkPath, ref) : pending;
+  const notes = (await Promise.all(ids.map((id) => readNote(forkPath, ref, id)))).map(
+    (note, i) => note ?? {
+      id: ids[i],
+      title: `${ids[i]} (no longer upstream)`,
+      summary: "",
+      syncBreaking: false,
+      clientCacheBump: false,
+      roots: [],
+      codemod: null
+    }
+  );
+  const total = (await listNoteIds(forkPath, ref)).length;
+  if (config.json) {
+    const open = new Set(pending);
+    const out = {
+      upstreamCommit: ref,
+      total,
+      open: pending.length,
+      notes: notes.map((note) => toJson(note, urlOf(note.id), open.has(note.id)))
+    };
+    writeStdout(JSON.stringify(out, null, 2));
+    return;
+  }
+  console.info(colors_default.dim(formatNotesLine(total, pending.length)));
+  if (notes.length === 0) return;
+  console.info();
+  for (const [i, note] of notes.entries()) printNote(i + 1, note, urlOf(note.id));
+  if (pending.length > 0) {
+    console.info(colors_default.dim("work each note's README, check with `pnpm check`, then record it:"));
+    console.info(colors_default.dim(`  pnpm cella migrate --mark ${pending.join(" ")}`));
+  }
+}
+
 // src/services/analyze.ts
 var scopeStatuses = {
   all: /* @__PURE__ */ new Set(["ahead", "drifted", "diverged"]),
@@ -2649,6 +3073,7 @@ async function runAnalyze(config) {
   printIgnoredUpstreamChanges(result);
   printUpstreamOverrideChanges(result);
   printMaskingPinWarning(result.files);
+  await printMigrationNotesLine(config, result);
   if (config.logFile) {
     const logPath = writeLogFile(config.forkPath, result.files);
     console.info();
@@ -3427,7 +3852,7 @@ async function checkOverrides(forkPath) {
 
 // src/services/contributions.ts
 import { readFileSync as readFileSync4 } from "fs";
-import { join as join13 } from "path";
+import { join as join16 } from "path";
 import {
   createPrompt,
   isDownKey,
@@ -3442,7 +3867,7 @@ import {
 import { select as select2 } from "@inquirer/prompts";
 
 // src/services/contrib-core.ts
-import { dirname as dirname3, join as join12, resolve as resolve3 } from "path";
+import { dirname as dirname5, join as join15, 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));
@@ -3458,10 +3883,10 @@ async function detectContributableFiles(repoPath, baseRef, forkRef, config, fork
   const baseFiles = await listFilesAtRef(repoPath, baseRef);
   const baseDirs = /* @__PURE__ */ new Set(["."]);
   for (const f of baseFiles) {
-    let dir = dirname3(f);
+    let dir = dirname5(f);
     while (dir !== ".") {
       baseDirs.add(dir);
-      dir = dirname3(dir);
+      dir = dirname5(dir);
     }
   }
   const files = [];
@@ -3474,7 +3899,7 @@ async function detectContributableFiles(repoPath, baseRef, forkRef, config, fork
     if (inCella && !inFork) {
       kind = "deleted";
     } else if (!inCella && inFork) {
-      if (!baseDirs.has(dirname3(file.path))) continue;
+      if (!baseDirs.has(dirname5(file.path))) continue;
       kind = "created";
     } else {
       kind = "modified";
@@ -3505,8 +3930,8 @@ async function readBlobInfo(repoPath, ref, filePath) {
 }
 async function buildContribBranch(repoPath, baseRef, forkRef, detection, forkName) {
   const branch = `contrib/${forkName}`;
-  const gitDir = resolve3(repoPath, await git(["rev-parse", "--git-dir"], repoPath));
-  const tmpIndex = join12(gitDir, `tmp-contrib-index-${forkName.replace(/[^\w.-]/g, "_")}`);
+  const gitDir = resolve5(repoPath, await git(["rev-parse", "--git-dir"], repoPath));
+  const tmpIndex = join15(gitDir, `tmp-contrib-index-${forkName.replace(/[^\w.-]/g, "_")}`);
   const indexEnv = { GIT_INDEX_FILE: tmpIndex };
   try {
     await git(["read-tree", baseRef], repoPath, { env: indexEnv });
@@ -3549,20 +3974,20 @@ ${commitBody}`;
 }
 
 // src/services/fork-utils.ts
-import { existsSync as existsSync7 } from "fs";
-import { dirname as dirname4, resolve as resolve4 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { dirname as dirname6, resolve as resolve6 } from "path";
 async function resolveForkBasePath(repoPath) {
   const commonDir = await git(["rev-parse", "--git-common-dir"], repoPath, { ignoreErrors: true });
-  return commonDir ? dirname4(resolve4(repoPath, commonDir)) : repoPath;
+  return commonDir ? dirname6(resolve6(repoPath, commonDir)) : repoPath;
 }
 function validateForkPath(fork, basePath, requireConfig = false) {
-  const resolvedPath = resolve4(basePath, fork.localPath);
-  if (!resolvedPath.startsWith(resolve4(basePath, ".."))) {
+  const resolvedPath = resolve6(basePath, fork.localPath);
+  if (!resolvedPath.startsWith(resolve6(basePath, ".."))) {
     return { fork, resolvedPath, valid: false, error: "path resolves outside parent directory" };
   }
-  if (!existsSync7(resolvedPath)) return { fork, resolvedPath, valid: false, error: "path does not exist" };
-  if (!existsSync7(`${resolvedPath}/.git`)) return { fork, resolvedPath, valid: false, error: "not a git repository" };
-  if (requireConfig && !existsSync7(`${resolvedPath}/${CONFIG_FILE}`)) {
+  if (!existsSync9(resolvedPath)) return { fork, resolvedPath, valid: false, error: "path does not exist" };
+  if (!existsSync9(`${resolvedPath}/.git`)) return { fork, resolvedPath, valid: false, error: "not a git repository" };
+  if (requireConfig && !existsSync9(`${resolvedPath}/${CONFIG_FILE}`)) {
     return { fork, resolvedPath, valid: false, error: `missing ${CONFIG_FILE}` };
   }
   return { fork, resolvedPath, valid: true };
@@ -3580,7 +4005,7 @@ async function showContribDiff(item, baseRef, cwd, forkName) {
   return openDiffInBrowser(patch.toString(), { filePath: item.path, srcLabel: "cella", dstLabel: forkName }, cwd);
 }
 function shouldApplyContributionsUnstaged(repoPath) {
-  return JSON.parse(readFileSync4(join13(repoPath, "package.json"), "utf8")).name === "cella";
+  return JSON.parse(readFileSync4(join16(repoPath, "package.json"), "utf8")).name === "cella";
 }
 var contribPrompt = createPrompt((config, done) => {
   const { pageSize = 20, baseRef, cwd, forkName } = config;
@@ -3925,7 +4350,7 @@ async function runContributions(config) {
 }
 
 // src/services/forks.ts
-import { resolve as resolve5 } from "path";
+import { resolve as resolve7 } from "path";
 import process8 from "process";
 import { Separator as Separator2, select as select4 } from "@inquirer/prompts";
 
@@ -3968,7 +4393,6 @@ function listOpenSyncPrs(cwd, prefix) {
 }
 function buildMergeArgs(ref, options = {}) {
   const args = ["pr", "merge", ref, "--squash"];
-  if (options.auto) args.push("--auto");
   if (options.deleteBranch) args.push("--delete-branch");
   return args;
 }
@@ -3980,12 +4404,12 @@ function closePr(cwd, ref) {
 }
 
 // src/services/packages.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { join as join18 } from "path";
 
 // src/services/package-usage.ts
-import { existsSync as existsSync8, readFileSync as readFileSync5, statSync } from "fs";
-import { join as join14 } from "path";
+import { existsSync as existsSync10, readFileSync as readFileSync5, statSync } from "fs";
+import { join as join17 } from "path";
 var MAX_FILE_BYTES = 1024 * 1024;
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -4001,7 +4425,7 @@ function readSearchable(filePath) {
 }
 function fileSource(forkPath, path4) {
   let text;
-  return { path: path4, label: path4, text: () => text ??= readSearchable(join14(forkPath, path4)) };
+  return { path: path4, label: path4, text: () => text ??= readSearchable(join17(forkPath, path4)) };
 }
 async function readScriptsAtRef(forkPath, ref, path4) {
   try {
@@ -4013,7 +4437,7 @@ async function readScriptsAtRef(forkPath, ref, path4) {
 async function scriptSources(forkPath, upstreamRef, baseRef, path4) {
   let forkScripts;
   try {
-    forkScripts = JSON.parse(readFileSync5(join14(forkPath, path4), "utf-8")).scripts ?? {};
+    forkScripts = JSON.parse(readFileSync5(join17(forkPath, path4), "utf-8")).scripts ?? {};
   } catch {
     return [];
   }
@@ -4023,9 +4447,9 @@ async function scriptSources(forkPath, upstreamRef, baseRef, path4) {
 }
 function binNames(forkPath, location, name) {
   const bareName = name.split("/").pop();
-  for (const dir of [join14(forkPath, location), forkPath]) {
-    const manifest = join14(dir, "node_modules", name, "package.json");
-    if (!existsSync8(manifest)) continue;
+  for (const dir of [join17(forkPath, location), forkPath]) {
+    const manifest = join17(dir, "node_modules", name, "package.json");
+    if (!existsSync10(manifest)) continue;
     try {
       const { bin } = JSON.parse(readFileSync5(manifest, "utf-8"));
       if (typeof bin === "string") return [bareName];
@@ -4067,26 +4491,6 @@ async function loadForkUsage(forkPath, upstreamRef, baseRef) {
 }
 
 // src/services/packages.ts
-function parseComparableVersion(version) {
-  const trimmed = version.trim();
-  if (trimmed === "" || trimmed === "*" || trimmed.includes("workspace:") || trimmed.includes("catalog:") || trimmed.includes("file:") || trimmed.includes("link:") || trimmed.includes("git+") || trimmed.includes("github:") || trimmed.includes("http://") || trimmed.includes("https://") || trimmed.includes("||")) {
-    return null;
-  }
-  const match = trimmed.match(
-    /^(?:\^|~|>=|<=|>|<|=)?\s*v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
-  );
-  if (!match) return null;
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2] ?? 0),
-    patch: Number(match[3] ?? 0)
-  };
-}
-function compareVersions(left, right) {
-  if (left.major !== right.major) return left.major - right.major;
-  if (left.minor !== right.minor) return left.minor - right.minor;
-  return left.patch - right.patch;
-}
 function isHigherVersion(upstreamVersion, forkVersion) {
   if (upstreamVersion === forkVersion) return false;
   const upCoerced = parseComparableVersion(upstreamVersion);
@@ -4204,8 +4608,28 @@ function safeMergePnpm(forkPnpm, upstreamPnpm, basePnpm) {
   }
   return { merged, changed };
 }
+function mergeModuleType(forkType, upstreamType, baseType) {
+  const asString = (value) => typeof value === "string" ? value : void 0;
+  const fork = asString(forkType);
+  const upstream = asString(upstreamType);
+  if (fork === upstream) return null;
+  if (fork === void 0) return { value: upstream, change: "added" };
+  if (fork !== asString(baseType)) return null;
+  return { value: upstream, change: upstream === void 0 ? "removed" : "updated" };
+}
+function setTopLevelKey(pkg, key, value) {
+  if (key in pkg) {
+    pkg[key] = value;
+    return;
+  }
+  const entries = Object.entries(pkg);
+  const after = Math.max(...["name", "version", "private"].map((name) => entries.findIndex(([k]) => k === name)));
+  entries.splice(after + 1, 0, [key, value]);
+  for (const name of Object.keys(pkg)) delete pkg[name];
+  Object.assign(pkg, Object.fromEntries(entries));
+}
 function readPackageJson(filePath) {
-  if (!existsSync9(filePath)) return null;
+  if (!existsSync11(filePath)) return null;
   try {
     return JSON.parse(readFileSync6(filePath, "utf-8"));
   } catch {
@@ -4243,13 +4667,13 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
   const changes = [];
   const kept = [];
   const pkgRelPath = packageJsonPath(relativePath);
-  const pkgPath = join15(forkPath, pkgRelPath);
+  const pkgPath = join18(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 !== "" && existsSync9(join15(forkPath, relativePath));
+    const workspaceArrived = relativePath !== "" && existsSync11(join18(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");
@@ -4257,6 +4681,13 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
   }
   const upstreamPkg = upstream.data;
   let updated = false;
+  const type = mergeModuleType(forkPkg.type, upstreamPkg.type, basePkg?.type);
+  if (type) {
+    if (type.value === void 0) delete forkPkg.type;
+    else setTopLevelKey(forkPkg, "type", type.value);
+    updated = true;
+    changes.push(`type: ${type.change}`);
+  }
   for (const key of keysToSync) {
     if (key === "pnpm") {
       const result2 = safeMergePnpm(forkPkg.pnpm, upstreamPkg.pnpm, basePkg?.pnpm);
@@ -4364,11 +4795,17 @@ async function runPackages(config, options = {}) {
 }
 
 // src/services/sync.ts
-async function ensureBaseUpToDate(forkPath, base) {
-  const { upstream, ahead, behind } = await getUpstreamStatus(forkPath);
+async function resolveCycleStart(forkPath, base, currentBranch) {
+  if (!await branchExists(forkPath, base)) {
+    await fetch2(forkPath, "origin").catch(() => {
+    });
+    console.info(colors_default.dim(`'${base}' has no local branch \u2014 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.`));
-    return;
+    return base;
   }
   if (ahead > 0 && behind > 0) {
     throw new Error(
@@ -4377,26 +4814,53 @@ Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-
     );
   }
   if (behind > 0) {
+    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.`)
+      );
+      return upstream;
+    }
     console.info(colors_default.dim(`fast-forwarding '${base}' to '${upstream}' (${behind} behind)...`));
-    await pullFastForward(forkPath);
-    return;
+    if (currentBranch === base) await pullFastForward(forkPath);
+    else await fastForwardBranch(forkPath, base, upstream);
+    return base;
   }
   if (ahead > 0) {
     console.info(colors_default.dim(`'${base}' is ${ahead} commit(s) ahead of '${upstream}' (unpushed) \u2014 continuing.`));
   }
+  return base;
 }
 async function setupTemporarySyncBranch(config) {
   const { forkPath, settings } = config;
   const base = resolveReleaseBase(settings);
   const startBranch = await getCurrentBranch(forkPath);
-  console.info(colors_default.dim(`switching to '${base}' and updating...`));
-  await switchBranch(forkPath, base);
-  await ensureBaseUpToDate(forkPath, base);
+  const startCommit = (await getCommitInfo(forkPath, "HEAD")).hash;
+  console.info(colors_default.dim(`updating '${base}'...`));
+  const startPoint = await resolveCycleStart(forkPath, base, startBranch);
   const temporaryBranch = buildTemporarySyncBranch();
-  console.info(colors_default.dim(`creating temporary sync branch '${temporaryBranch}' from '${base}'...`));
+  console.info(colors_default.dim(`creating temporary sync branch '${temporaryBranch}' from '${startPoint}'...`));
   console.info();
-  await createBranchFrom(forkPath, temporaryBranch, base);
-  return { temporaryBranch, base, startBranch };
+  await createBranchFrom(forkPath, temporaryBranch, startPoint);
+  return { temporaryBranch, base, startBranch, startCommit };
+}
+async function resolveCutBase(forkPath, base) {
+  if (!await branchExists(forkPath, base)) return `origin/${base}`;
+  const upstream = await getBranchUpstream(forkPath, base);
+  return upstream && await isAncestor(forkPath, base, upstream) ? upstream : 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...`));
+    await switchDetached(forkPath, base);
+    return `detached at '${base}'`;
+  }
+  console.info(colors_default.dim(`switching back to '${base}'...`));
+  await switchBranch(forkPath, base);
+  await pullFastForward(forkPath).catch(() => {
+  });
+  return `back on '${base}'`;
 }
 async function runSync(config, options) {
   createSpinner("starting sync...");
@@ -4427,6 +4891,7 @@ async function runSync(config, options) {
   const stagedBranch = options?.stagedBranch && result.conflicts.length === 0 && hasStagedSyncChanges(result) ? options.stagedBranch : void 0;
   printSyncComplete(result, { stagedBranch });
   printFlagWarnings({ hard: config.hard, unpinned: config.unpinned });
+  await printMigrationNotesLine(config, result);
   return result;
 }
 var SYNC_PR_TITLE = "chore: sync upstream cella";
@@ -4443,7 +4908,7 @@ function qualifyPrRefs(subject, repoSlug) {
   return subject.replace(/(^|[^\w/])#(\d+)\b/g, `$1${repoSlug}#$2`);
 }
 function buildSyncPrBody(input) {
-  const { repoSlug, version, fromSha, toSha, commits, totalCount } = input;
+  const { repoSlug, version, fromSha, toSha, commits, totalCount, notes } = input;
   const githubUrl = repoSlug ? `https://github.com/${repoSlug}` : void 0;
   const short = (sha) => sha.slice(0, 7);
   const commitRef = (sha) => githubUrl ? `[\`${short(sha)}\`](${githubUrl}/commit/${sha})` : `\`${short(sha)}\``;
@@ -4458,6 +4923,19 @@ function buildSyncPrBody(input) {
       lines.push(`- ${commitRef(commit.hash)} ${qualifyPrRefs(commit.message, repoSlug)}`);
     }
   }
+  if (notes && notes.total > 0) {
+    const { total, open } = notes;
+    if (open.length === 0) lines.push("", `**Migration notes**: all ${total} handled.`);
+    else {
+      lines.push(
+        "",
+        `**Migration notes**: ${Math.max(0, total - open.length)} of ${total} handled, open (\`pnpm cella migrate\`):`,
+        ""
+      );
+      for (const note of open)
+        lines.push(`- ${note.url ? `[${note.title}](${note.url})` : note.title} (\`${note.id}\`)`);
+    }
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -4473,7 +4951,20 @@ async function buildSyncPrBodyForBranch(forkPath, base) {
     skip: totalCount > PR_BODY_COMMIT_MAX ? totalCount - PR_BODY_COMMIT_MAX : 0,
     limit: PR_BODY_COMMIT_MAX
   }) : [];
-  return buildSyncPrBody({ repoSlug: manifest.upstream.repo, version, fromSha, toSha, commits, totalCount });
+  const notes = await readPrBodyNotes(forkPath, toSha, manifest.upstream.repo).catch(() => void 0);
+  return buildSyncPrBody({ repoSlug: manifest.upstream.repo, version, fromSha, toSha, commits, totalCount, notes });
+}
+async function readPrBodyNotes(forkPath, toSha, repoSlug) {
+  const githubUrl = repoSlug ? `https://github.com/${repoSlug}` : void 0;
+  const [ids, pending] = await Promise.all([listNoteIds(forkPath, toSha), readPending(forkPath, toSha)]);
+  const open = await Promise.all(
+    pending.map(async (id) => ({
+      id,
+      title: (await readNote(forkPath, toSha, id))?.title ?? id,
+      url: noteUrl(githubUrl, toSha, id)
+    }))
+  );
+  return { total: ids.length, open };
 }
 function printPrCreateStep(branch, base, title = SYNC_PR_TITLE) {
   console.info(colors_default.dim(`  gh pr create --base ${base} --head ${branch} --title "${title}" --fill`));
@@ -4507,22 +4998,13 @@ async function flattenSyncBranch(forkPath, branch, base) {
 function indentLines(text) {
   return text.split("\n").map((line) => `  ${line}`).join("\n");
 }
-function enableAutoMerge(forkPath, branch) {
-  console.info(colors_default.dim("enabling auto-merge (squash) once checks pass..."));
-  const merge2 = mergePrSquash(forkPath, branch, { auto: true, deleteBranch: true });
-  if (merge2.ok) return true;
-  console.info(colors_default.yellow("could not enable auto-merge (is it enabled for the repo?). merge it manually:"));
-  if (merge2.output) console.info(colors_default.dim(indentLines(merge2.output)));
-  console.info(colors_default.dim(`  gh pr merge ${branch} --squash --delete-branch`));
-  return false;
-}
 async function shipSyncBranch(config, branch) {
   const { forkPath, settings } = config;
   const base = resolveReleaseBase(settings);
-  const flattened = await flattenSyncBranch(forkPath, branch, base);
+  const cutBase = await resolveCutBase(forkPath, base);
+  const flattened = await flattenSyncBranch(forkPath, branch, cutBase);
   let prUrl;
   let prOpened = false;
-  let autoMergeEnabled = false;
   const headSubject = (await getCommitInfo(forkPath, "HEAD").catch(() => null))?.message;
   const prTitle = headSubject?.startsWith(SYNC_PR_TITLE) ? headSubject : SYNC_PR_TITLE;
   console.info(colors_default.dim(`pushing '${branch}' to origin...`));
@@ -4536,7 +5018,7 @@ async function shipSyncBranch(config, branch) {
   }
   if (ghAvailable()) {
     console.info(colors_default.dim("opening a pull request..."));
-    const prBody = await buildSyncPrBodyForBranch(forkPath, base);
+    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], {
       cwd: forkPath,
@@ -4546,9 +5028,7 @@ async function shipSyncBranch(config, branch) {
     prUrl = extractFirstUrl(`${pr.stdout ?? ""}
 ${pr.stderr ?? ""}`);
     prOpened = pr.status === 0;
-    if (prOpened) {
-      if (config.directMerge) autoMergeEnabled = enableAutoMerge(forkPath, branch);
-    } else {
+    if (!prOpened) {
       console.info(colors_default.yellow("could not open the PR automatically (it may already exist). open it with:"));
       if (prUrl) console.info(colors_default.dim(`  ${prUrl}`));
       printPrCreateStep(branch, base, prTitle);
@@ -4557,19 +5037,16 @@ ${pr.stderr ?? ""}`);
     console.info(colors_default.yellow("`gh` not found \u2014 open the PR manually:"));
     printPrCreateStep(branch, base, prTitle);
   }
-  console.info(colors_default.dim(`switching back to '${base}'...`));
-  await switchBranch(forkPath, base);
-  await pullFastForward(forkPath).catch(() => {
-  });
+  const position = await returnToBase(forkPath, base);
   console.info();
   if (prUrl) {
     console.info(`${colors_default.green("\u2713")} Sync pull request ${prOpened ? "opened" : "ready"}`);
-    const status = autoMergeEnabled ? `auto-merge on \u2014 squashes into '${base}' when checks pass` : `branch pushed, back on '${base}'`;
-    console.info(colors_default.dim(`  ${prUrl} \xB7 ${status}`));
+    console.info(colors_default.dim(`  ${prUrl} \xB7 branch pushed, ${position}`));
   } else {
     console.info(`${colors_default.green("\u2713")} Sync branch pushed`);
-    console.info(colors_default.dim(`  '${branch}' is on origin, back on '${base}'`));
+    console.info(colors_default.dim(`  '${branch}' is on origin, ${position}`));
   }
+  await printMigrationNotesLine(config);
 }
 function finalizeWorkspace(forkPath) {
   for (const args of [["install"], ["check"]]) {
@@ -4587,8 +5064,9 @@ async function runSyncCycle(config) {
     await runPackages(config, { conflictedFiles: result.conflicts });
   }
   if (result.conflicts.length > 0) return { status: "conflicts", branch };
-  if (!mergeInProgress(forkPath)) {
-    await switchBranch(forkPath, branch.startBranch === branch.temporaryBranch ? branch.base : branch.startBranch);
+  if (!await mergeInProgress(forkPath)) {
+    if (branch.startBranch === "HEAD") await switchDetached(forkPath, branch.startCommit);
+    else await switchBranch(forkPath, branch.startBranch);
     await deleteBranch(forkPath, branch.temporaryBranch);
     return { status: "noop" };
   }
@@ -4618,6 +5096,7 @@ async function commitSyncMerge(config, branch) {
   console.info();
   console.info(colors_default.green(`committed the sync on '${branch}' as '${message}'.`));
   printTriageSteps(branch);
+  await printMigrationNotesLine(config);
 }
 function printTriageSteps(branch) {
   console.info(colors_default.dim(`staying on '${branch}' without pushing.`));
@@ -4645,9 +5124,6 @@ async function mergeOpenSyncPrs(config, open) {
     closePr(forkPath, pr.number);
     await deleteBranch(forkPath, pr.headRefName);
   }
-  console.info(colors_default.dim(`switching to '${base}' and fast-forwarding...`));
-  await switchBranch(forkPath, base);
-  await pullFastForward(forkPath);
   return "continue";
 }
 async function guardAgainstOpenSyncPr(config) {
@@ -4686,7 +5162,7 @@ async function runSyncCommand(config) {
   const { forkPath } = config;
   const currentBranch = await getCurrentBranch(forkPath);
   const onSyncBranch = isTemporarySyncBranch(currentBranch);
-  if (onSyncBranch && mergeInProgress(forkPath)) {
+  if (onSyncBranch && await mergeInProgress(forkPath)) {
     await commitSyncMerge(config, currentBranch);
     return;
   }
@@ -4809,7 +5285,7 @@ async function runForks(config) {
       console.error(colors_default.red(`fork '${config.fork}' not found in config`));
       return;
     }
-    const resolvedPath = resolve5(await resolveForkBasePath(config.forkPath), match.localPath);
+    const resolvedPath = resolve7(await resolveForkBasePath(config.forkPath), match.localPath);
     await syncFork(config, match, resolvedPath);
     return;
   }
@@ -4825,7 +5301,7 @@ async function runForks(config) {
     if (selectedPath === "_exit") {
       process8.exit(0);
     }
-    const resolvedForkPath = resolve5(forkBasePath, selectedPath);
+    const resolvedForkPath = resolve7(forkBasePath, selectedPath);
     const selectedFork = forks.find((f) => f.localPath === selectedPath);
     if (!selectedFork) {
       console.error(colors_default.red(`fork '${selectedPath}' not found in config`));
@@ -4837,8 +5313,8 @@ async function runForks(config) {
 }
 
 // src/services/stats.ts
-import { readFile as readFile2 } from "fs/promises";
-import { join as join17 } from "path";
+import { readFile as readFile3 } from "fs/promises";
+import { join as join20 } from "path";
 
 // src/utils/coverage-utils.ts
 import { spawnSync as spawnSync4 } from "child_process";
@@ -4932,7 +5408,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 readFile2(join17(forkPath, "pnpm-workspace.yaml"), "utf-8");
+  const content = await readFile3(join20(forkPath, "pnpm-workspace.yaml"), "utf-8");
   return parseYamlBlockList(content, "packages").map((pattern) => {
     if (pattern.endsWith("/*")) {
       const base = pattern.slice(0, -2);
@@ -5095,20 +5571,20 @@ async function runStats(forkPath, options = {}) {
 function getForkPath() {
   const envPath = getEnv("CELLA_FORK_PATH");
   if (envPath) {
-    const resolved = resolve6(envPath);
-    if (!existsSync11(resolved) || !statSync3(resolved).isDirectory()) {
+    const resolved = resolve8(envPath);
+    if (!existsSync13(resolved) || !statSync3(resolved).isDirectory()) {
       throw new Error(`CELLA_FORK_PATH is not a valid directory: ${resolved}`);
     }
     return resolved;
   }
   let cwd = process9.cwd();
   if (cwd.endsWith("/cli/cella") || cwd.endsWith("\\cli\\cella")) {
-    cwd = resolve6(cwd, "../..");
+    cwd = resolve8(cwd, "../..");
   }
   return cwd;
 }
 async function preflight(forkPath) {
-  if (!existsSync11(join18(forkPath, ".git"))) {
+  if (!existsSync13(join21(forkPath, ".git"))) {
     throw new Error(`not a git repository: ${forkPath}`);
   }
 }
@@ -5137,6 +5613,9 @@ async function main() {
         await runSyncCommand(config);
         break;
       }
+      case "migrate":
+        await runMigrate(config);
+        break;
       case "audit":
         await runAudit(config, { force: config.force, checkOverrides: config.checkOverrides });
         break;