@cellajs/cli 0.6.6 → 0.6.7

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/config/types.ts"],"sourcesContent":["/**\n * Configuration types: the public cella/cella.config.ts surface, its runtime\n * schema, and the internal types the services share.\n */\n\nimport { z } from 'zod';\n\n// Public API for cella/cella.config.ts.\n\nconst PACKAGE_JSON_KEYS = [\n  'dependencies',\n  'devDependencies',\n  'peerDependencies',\n  'optionalDependencies',\n  'scripts',\n  'engines',\n  'packageManager',\n  'overrides',\n  'exports',\n  'pnpm',\n] as const;\n\n/** Valid package.json keys that can merge from upstream */\nexport type PackageJsonKey = (typeof PACKAGE_JSON_KEYS)[number];\n\n/**\n * Settings: all configurable options for the cella CLI.\n * Hover over each property for documentation.\n */\nexport interface SyncSettings {\n  /** Upstream repository URL (e.g., 'git@github.com:cellajs/cella.git') */\n  upstreamUrl: string;\n\n  /**\n   * Upstream branch, used for `upstreamTrack: 'branch'` and for GitHub file links.\n   * Defaults to 'main'.\n   */\n  upstreamBranch?: string;\n\n  /**\n   * How to track upstream cella. Defaults to 'release'.\n   * - 'release' (default): upgrade to a published cella release tag (`0.18.1`, with or without `v`). Stable and\n   *   reviewable: each bump maps to a changelog. Uses the latest release.\n   * - 'branch': follow the bleeding-edge tip of `upstreamBranch`. For cella\n   *   maintainers and forks doing active development on top of unreleased changes.\n   */\n  upstreamTrack?: 'release' | 'branch';\n\n  /**\n   * Trunk branch that `pnpm cella upgrade` cuts the temporary branch from and that you open the\n   * squash-merge PR into. Defaults to 'main'. Cutting fresh from trunk each cycle keeps every\n   * PR limited to that cycle's upstream delta (no accumulation) and `main` linear.\n   */\n  releaseBase?: string;\n\n  /** Which package.json keys merge from upstream (default: ['dependencies', 'devDependencies']). `type` always merges. */\n  packageJsonKeys?: PackageJsonKey[];\n\n  /** Merge the `packageJsonKeys` of every package.json after the upgrade merge (default: true). */\n  mergePackageJson?: boolean;\n\n  /** @deprecated Renamed to `packageJsonKeys`. */\n  packageJsonSync?: PackageJsonKey[];\n\n  /** @deprecated Renamed to `mergePackageJson`. */\n  syncWithPackages?: boolean;\n\n  /**\n   * How to link files in CLI output.\n   * - 'commit' (default): Link to the commit that changed the file on GitHub.\n   * - 'file': Link to the file in the repo at the upstream branch on GitHub.\n   */\n  fileLinkMode?: 'commit' | 'file';\n}\n\n/**\n * Configuration for a downstream fork repository that cella interacts with.\n *\n * Cella is the upstream/source-of-truth. For each fork it can:\n * - pull contributions FROM the fork's `pullBranch` (contributions service)\n * - run the normal temporary-branch upgrade flow inside the fork (forks service)\n */\nexport interface ForkConfig {\n  /** Display name for the fork (also used as the contrib/<name> branch slug) */\n  name: string;\n  /** Local path to the fork repository (relative to this config or absolute) */\n  localPath: string;\n  /**\n   * Git remote URL of the fork (e.g. 'git@github.com:org/fork.git').\n   * When set, the contributions service fetches the fork's `pullBranch` from this\n   * remote (the authoritative committed ref), so the comparison does not depend on\n   * the local checkout being up to date. The local clone is still used to read the\n   * fork's owned-folder territory when available.\n   */\n  remoteUrl?: string;\n  /** Fork branch that cella pulls contributions from (contributions service) */\n  pullBranch: string;\n}\n\n/** User-configurable sync options for cella/cella.config.ts. */\nexport interface CellaCliConfig {\n  /** Core sync settings */\n  settings: SyncSettings;\n\n  /**\n   * File overrides for controlling sync behavior per folder/file.\n   */\n  overrides?: {\n    /**\n     * Paths the fork fully owns: never synced (existing or new).\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Local territory: upstream cannot add, modify, or delete anything under these.\n     */\n    ignored?: string[];\n\n    /**\n     * Paths pinned to the fork: the fork copy wins whole-file.\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Upstream changes to a pinned file are dropped, not merged: analyze lists them under\n     * \"protected but behind upstream\" to adopt by hand.\n     * If fork deleted a pinned file, deletion is respected.\n     */\n    pinned?: string[];\n  };\n\n  /**\n   * Downstream fork repositories that cella interacts with (for upstream template repos).\n   * When configured, the 'forks' and 'contributions' services appear in the CLI menu.\n   */\n  forks?: ForkConfig[];\n}\n\n/**\n * Helper function for defining cella/cella.config.ts with type checking.\n */\nexport function defineConfig(config: CellaCliConfig): CellaCliConfig {\n  return config;\n}\n\n/**\n * Strict runtime schema mirroring {@link CellaCliConfig}.\n *\n * The TS interfaces above stay the source of truth (and keep their hover docs for\n * config authors). This schema is what's enforced at load time: `.strict()` rejects\n * unknown keys, so a typo like `ignoredFolders` for `ignored` fails closed; a silent\n * fallback would drop sync protection (tsx does not typecheck the config).\n *\n * The `satisfies z.ZodType<CellaCliConfig>` assertion keeps schema and interface in\n * lockstep: if either drifts (a renamed/removed/mis-typed field), TypeScript errors here.\n */\nexport const cellaConfigSchema = z\n  .object({\n    settings: z\n      .object({\n        upstreamUrl: z.string().min(1),\n        upstreamBranch: z.string().min(1).optional(),\n        upstreamTrack: z.enum(['release', 'branch']).optional(),\n        releaseBase: z.string().min(1).optional(),\n        packageJsonKeys: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),\n        mergePackageJson: z.boolean().optional(),\n        packageJsonSync: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),\n        syncWithPackages: z.boolean().optional(),\n        fileLinkMode: z.enum(['commit', 'file']).optional(),\n      })\n      .strict(),\n    overrides: z\n      .object({\n        ignored: z.array(z.string()).optional(),\n        pinned: z.array(z.string()).optional(),\n      })\n      .strict()\n      .optional(),\n    forks: z\n      .array(\n        z\n          .object({\n            name: z.string().min(1),\n            localPath: z.string().min(1),\n            remoteUrl: z.string().optional(),\n            pullBranch: z.string().min(1),\n          })\n          .strict(),\n      )\n      .optional(),\n  })\n  .strict() satisfies z.ZodType<CellaCliConfig>;\n\n// Internal types for the services.\n\n/** Sync services available in the CLI */\nexport type SyncService = 'analyze' | 'upgrade' | 'align' | 'audit' | 'forks' | 'contributions' | 'stats';\n\n/** Where a command shows in the menu and in `--help`; a gate shows in `--help` only, since scripts and CI run it. */\nexport type CommandGroup = 'develop' | 'security' | 'upstream' | 'gate';\n\nexport type CommandOption = [flags: string, description: string];\n\n/**\n * A command that runs without the upgrade config: no `cella.config.ts`, no override validation. It declares its own\n * options, parses them into its own shape and returns its exit code.\n */\nexport interface ToolCommand<Options = unknown> {\n  name: string;\n  group: Exclude<CommandGroup, 'upstream'>;\n  description: string;\n  /** The jobs its first operand names, the default first; the menu asks for one. Empty: the command has one job. */\n  jobs: [name: string, description: string][];\n  /**\n   * The words it takes after the job, in commander's notation such as `[scenario]` or `[paths...]`; none when unset.\n   * A command takes these or a passthrough, never both.\n   */\n  operands?: CommandOption;\n  options?: CommandOption[];\n  /** What the words after `--` are for, in `--help`. */\n  passthrough?: CommandOption;\n  parse(input: { job?: string; operands: string[]; opts: Record<string, unknown>; passthrough: string[] }): Options;\n  run(forkPath: string, options: Options): Promise<number>;\n}\n\n/** Analyze output scope for interactive and machine-readable flows */\nexport type AnalyzeScope = 'all' | 'risk' | 'protected';\n\n/** Runtime configuration with all resolved values */\nexport interface RuntimeConfig extends CellaCliConfig {\n  /** Resolved fork repository path */\n  forkPath: string;\n\n  /** Full upstream remote ref (e.g., 'cella-upstream/development') */\n  upstreamRef: string;\n\n  /** Selected sync service */\n  service: SyncService;\n\n  /** Non-interactive list output (for LLM/agent usage) */\n  list: boolean;\n\n  /** Machine-readable JSON output (for tooling/agent usage) */\n  json: boolean;\n\n  /** Scope of files returned in analyze list/json output */\n  scope?: AnalyzeScope;\n\n  /** Show verbose output */\n  verbose: boolean;\n\n  /** Pre-selected fork name (skips fork selection prompt) */\n  fork?: string;\n\n  /**\n   * Override upstream tracking for this run (analyze/upgrade), ignoring `settings.upstreamTrack`.\n   * 'branch' follows the upstream branch tip (bleeding edge); 'release' uses a release tag.\n   */\n  track?: 'release' | 'branch';\n\n  /**\n   * Pin the upstream ref for this run (analyze/upgrade), overriding `track`: a commit sha, a release\n   * tag or an upstream branch name. Must be on the upstream branch or in an upstream release.\n   */\n  ref?: string;\n\n  /**\n   * Merge with the fork's CLI config as it stands (upgrade service). Without it, a new merge stops\n   * before anything changes when upstream changed its own `overrides` or `packageJsonKeys` in ways\n   * the fork config does not follow.\n   */\n  keepConfig?: boolean;\n\n  /**\n   * Lift every pinned entry for this run (analyze, sync): managed files stay pinned, and the merge\n   * uses the full upstream history, so upstream changes that earlier syncs dropped come back too.\n   */\n  unpinned?: boolean;\n\n  /** Count what the current branch changed since it left this ref, by kind of file (stats service) */\n  since?: string;\n\n  /** Print the `since` table as markdown for a pull request description (stats service) */\n  md?: boolean;\n\n  /** List every file instead of collapsing large groups (analyze), or every upstream alignment (align) */\n  all?: boolean;\n\n  /** Print one alignment's README (align service) */\n  show?: string;\n\n  /** Write one alignment's folder where its codemod can run (align service) */\n  extract?: string;\n\n  /** Run one alignment's codemod, keeping files identical to upstream as they are (align service) */\n  run?: string;\n\n  /** Arguments after `--`, passed to the codemod as given (align service, with `run`) */\n  runArgs?: string[];\n\n  /** Alignment ids to record as handled (align service) */\n  mark?: string[];\n}\n\n/** File status after analysis */\nexport type FileStatus =\n  | 'identical' // No changes needed\n  | 'ahead' // Fork is ahead, protected (pinned/ignored)\n  | 'local' // Local file (never existed upstream)\n  | 'drifted' // Fork is ahead, NOT protected (at risk)\n  | 'behind' // Upstream has changes to sync\n  | 'diverged' // Both changed, will merge\n  | 'pinned' // Fork wins on conflict\n  | 'ignored' // Excluded from sync entirely\n  | 'deleted' // Fork deleted, will stay deleted\n  | 'renamed'; // Upstream renamed file\n\n/** Statuses the sync applies changes for: a staged sync holds at least one file with one of these. */\nexport const SYNC_APPLIED_STATUSES: readonly FileStatus[] = ['behind', 'diverged', 'renamed', 'ignored', 'pinned'];\n\n/** Commit metadata for a single log entry */\nexport interface CommitRangeEntry {\n  hash: string;\n  message: string;\n  date: string;\n  /** Unix epoch seconds of the commit */\n  timestamp?: number;\n}\n\n/** Analyzed file with status and metadata */\nexport interface AnalyzedFile {\n  path: string;\n  status: FileStatus;\n  /** True if file is in ignored list */\n  isIgnored: boolean;\n  /** True if file is in pinned list */\n  isPinned: boolean;\n  /** True if file exists in fork */\n  existsInFork: boolean;\n  /** True if file exists in upstream */\n  existsInUpstream: boolean;\n  /** Relative date when file was last changed (since merge-base) */\n  changedAt?: string;\n  /** Unix epoch seconds of the last change, for sorting */\n  changedTs?: number;\n  /** Short commit hash of the last change */\n  changedCommit?: string;\n  /** For diverged files: relative date of upstream change */\n  upstreamChangedAt?: string;\n  /** For diverged files: Unix epoch seconds of the upstream change, for sorting */\n  upstreamChangedTs?: number;\n  /** For diverged files: short commit hash of the upstream change */\n  upstreamCommit?: string;\n  /** For renamed files: the original path before rename */\n  renamedFrom?: string;\n  /**\n   * Protected (pinned/ignored) files only: both sides changed since the merge-base. The fork\n   * side wins whole-file, so upstream's changes to this path are dropped by the sync.\n   */\n  upstreamChanged?: boolean;\n  /** For `upstreamChanged` and `upstreamOnly` files: lines upstream changed since the merge-base (undefined for binary) */\n  upstreamChangedLines?: number;\n  /**\n   * Ignored files only: upstream changed, added or deleted the file since the merge-base and the\n   * fork did not touch it. Ignored paths never sync, so without this flag the change stays unseen\n   * (new config keys, version bumps). Managed files and generated output (`isGeneratedFile`) are\n   * never flagged.\n   */\n  upstreamOnly?: boolean;\n  /**\n   * Pinned `ahead` files only: lines present upstream but absent from the fork (undefined for\n   * binary). Independent of the sync point, so it also shows upstream content dropped by an\n   * earlier sync, or removed on purpose; only a diff can tell.\n   */\n  upstreamLinesAbsent?: number;\n}\n\n/** Summary counts by status */\nexport interface AnalysisSummary {\n  /** Changed package/config files that are handled separately from normal sync categories */\n  managed: number;\n  identical: number;\n  ahead: number;\n  local: number;\n  drifted: number;\n  behind: number;\n  diverged: number;\n  pinned: number;\n  ignored: number;\n  deleted: number;\n  renamed: number;\n}\n\n/** Merge result from merge-engine */\nexport interface MergeResult {\n  success: boolean;\n  /** Upstream branch name for file links */\n  upstreamBranch?: string;\n  /** Resolved concrete upstream ref that was merged (branch ref or release tag ref) */\n  upstreamRef?: string;\n  /** Upstream release tag synced (when tracking releases) */\n  upstreamTag?: string;\n  files: AnalyzedFile[];\n  summary: AnalysisSummary;\n  conflicts: string[];\n  /** Upstream GitHub URL base for commit links */\n  upstreamGitHubUrl?: string;\n  /** Upstream commit info */\n  upstreamCommit?: CommitRangeEntry;\n  /** Upstream commits since the last sync point */\n  upstreamCommitCount?: number;\n  /** Files that were auto-merged by git (diverged without remaining conflicts) */\n  autoMergedFiles?: string[];\n  /**\n   * Protected (pinned/ignored) files resolved to the fork side although upstream also changed\n   * them: upstream's hunks were dropped, not merged. Review each against upstream.\n   */\n  protectedConflicts?: string[];\n  /** `<merge-base>..<upstream>` range of short SHAs: what upstream changed since the last sync, for the review page. */\n  upstreamDiffRange?: string;\n  /** How upstream's own CLI config changed since the merge-base, where the fork config does not follow. */\n  upstreamOverrides?: UpstreamOverridesReport;\n  /** Files flagged `upstreamOnly`, grouped by the `ignored` entry they fall under (config order). */\n  ignoredUpstreamChanges?: IgnoredUpstreamGroup[];\n  /**\n   * Upstream alignments: how many the incoming ref holds, which ones upstream added since the\n   * sync point, and the ones open in the fork after the run. A sync opens the arrivals; a dry run\n   * leaves them out of `open`.\n   */\n  alignments?: { total: number; arrived: string[]; open: string[] };\n}\n\n/** Entries of one CLI config list (`pinned`, `ignored` or `packageJsonKeys`) that the fork config does not mirror. */\nexport interface OverrideListChanges {\n  /** Entries upstream added since the merge-base that the fork list lacks. */\n  added: string[];\n  /** Entries upstream removed since the merge-base that the fork list still carries. */\n  removed: string[];\n}\n\n/**\n * Upstream CLI config changes the fork should review. The CLI config is managed (never merged),\n * so new upstream `pinned`/`ignored` entries and `packageJsonKeys` only reach the fork by\n * hand. `unreadable` means upstream's config was missing or unparsable at one side (`base` =\n * merge-base, `incoming` = upstream ref), so nothing was compared.\n */\nexport type UpstreamOverridesReport =\n  | {\n      kind: 'changes';\n      pinned: OverrideListChanges;\n      ignored: OverrideListChanges;\n      packageJsonKeys: OverrideListChanges;\n    }\n  | { kind: 'unreadable'; side: 'base' | 'incoming' };\n\n/** Upstream-only changes under one `ignored` entry. */\nexport interface IgnoredUpstreamGroup {\n  /** The `ignored` entry (configured or derived from an app-owned module) the files fall under. */\n  entry: string;\n  /** Changed paths under the entry, sorted. */\n  paths: string[];\n  /** Paths the fork lacks (new upstream files). */\n  added: number;\n  /** Paths upstream deleted (the fork keeps them). */\n  deleted: number;\n}\n"],"mappings":";AAKA,SAAS,SAAS;AAIlB,IAAM,oBAAoB;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAqHO,SAAS,aAAa,QAAwC;AACnE,SAAO;AACT;AAaO,IAAM,oBAAoB,EAC9B,OAAO;AAAA,EACN,UAAU,EACP,OAAO;AAAA,IACN,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC7B,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IAC3C,eAAe,EAAE,KAAK,CAAC,WAAW,QAAQ,CAAC,EAAE,SAAS;AAAA,IACtD,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IACxC,iBAAiB,EAAE,MAAM,EAAE,KAAK,iBAAiB,CAAC,EAAE,SAAS;AAAA,IAC7D,kBAAkB,EAAE,QAAQ,EAAE,SAAS;AAAA,IACvC,iBAAiB,EAAE,MAAM,EAAE,KAAK,iBAAiB,CAAC,EAAE,SAAS;AAAA,IAC7D,kBAAkB,EAAE,QAAQ,EAAE,SAAS;AAAA,IACvC,cAAc,EAAE,KAAK,CAAC,UAAU,MAAM,CAAC,EAAE,SAAS;AAAA,EACpD,CAAC,EACA,OAAO;AAAA,EACV,WAAW,EACR,OAAO;AAAA,IACN,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,IACtC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EACvC,CAAC,EACA,OAAO,EACP,SAAS;AAAA,EACZ,OAAO,EACJ;AAAA,IACC,EACG,OAAO;AAAA,MACN,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MACtB,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MAC3B,WAAW,EAAE,OAAO,EAAE,SAAS;AAAA,MAC/B,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC9B,CAAC,EACA,OAAO;AAAA,EACZ,EACC,SAAS;AACd,CAAC,EACA,OAAO;","names":[]}
+{"version":3,"sources":["../src/config/types.ts"],"sourcesContent":["/**\n * Configuration types: the public cella/cella.config.ts surface, its runtime\n * schema, and the internal types the services share.\n */\n\nimport { z } from 'zod';\n\n// Public API for cella/cella.config.ts.\n\nconst PACKAGE_JSON_KEYS = [\n  'dependencies',\n  'devDependencies',\n  'peerDependencies',\n  'optionalDependencies',\n  'scripts',\n  'engines',\n  'packageManager',\n  'overrides',\n  'exports',\n  'pnpm',\n] as const;\n\n/** Valid package.json keys that can merge from upstream */\nexport type PackageJsonKey = (typeof PACKAGE_JSON_KEYS)[number];\n\n/**\n * Settings: all configurable options for the cella CLI.\n * Hover over each property for documentation.\n */\nexport interface SyncSettings {\n  /** Upstream repository URL (e.g., 'git@github.com:cellajs/cella.git') */\n  upstreamUrl: string;\n\n  /**\n   * Upstream branch, used for `upstreamTrack: 'branch'` and for GitHub file links.\n   * Defaults to 'main'.\n   */\n  upstreamBranch?: string;\n\n  /**\n   * How to track upstream cella. Defaults to 'release'.\n   * - 'release' (default): upgrade to a published cella release tag (`0.18.1`, with or without `v`). Stable and\n   *   reviewable: each bump maps to a changelog. Uses the latest release.\n   * - 'branch': follow the bleeding-edge tip of `upstreamBranch`. For cella\n   *   maintainers and forks doing active development on top of unreleased changes.\n   */\n  upstreamTrack?: 'release' | 'branch';\n\n  /**\n   * Trunk branch that `pnpm cella upgrade` cuts the temporary branch from and that you open the\n   * squash-merge PR into. Defaults to 'main'. Cutting fresh from trunk each cycle keeps every\n   * PR limited to that cycle's upstream delta (no accumulation) and `main` linear.\n   */\n  releaseBase?: string;\n\n  /** Which package.json keys merge from upstream (default: ['dependencies', 'devDependencies']). `type` always merges. */\n  packageJsonKeys?: PackageJsonKey[];\n\n  /** Merge the `packageJsonKeys` of every package.json after the upgrade merge (default: true). */\n  mergePackageJson?: boolean;\n\n  /** @deprecated Renamed to `packageJsonKeys`. */\n  packageJsonSync?: PackageJsonKey[];\n\n  /** @deprecated Renamed to `mergePackageJson`. */\n  syncWithPackages?: boolean;\n\n  /**\n   * How to link files in CLI output.\n   * - 'commit' (default): Link to the commit that changed the file on GitHub.\n   * - 'file': Link to the file in the repo at the upstream branch on GitHub.\n   */\n  fileLinkMode?: 'commit' | 'file';\n}\n\n/**\n * Configuration for a downstream fork repository that cella interacts with.\n *\n * Cella is the upstream/source-of-truth. For each fork it can:\n * - pull contributions FROM the fork's `pullBranch` (contributions service)\n * - run the normal temporary-branch upgrade flow inside the fork (forks service)\n */\nexport interface ForkConfig {\n  /** Display name for the fork (also used as the contrib/<name> branch slug) */\n  name: string;\n  /** Local path to the fork repository (relative to this config or absolute) */\n  localPath: string;\n  /**\n   * Git remote URL of the fork (e.g. 'git@github.com:org/fork.git').\n   * When set, the contributions service fetches the fork's `pullBranch` from this\n   * remote (the authoritative committed ref), so the comparison does not depend on\n   * the local checkout being up to date. The local clone is still used to read the\n   * fork's owned-folder territory when available.\n   */\n  remoteUrl?: string;\n  /** Fork branch that cella pulls contributions from (contributions service) */\n  pullBranch: string;\n}\n\n/** User-configurable sync options for cella/cella.config.ts. */\nexport interface CellaCliConfig {\n  /** Core sync settings */\n  settings: SyncSettings;\n\n  /**\n   * File overrides for controlling sync behavior per folder/file.\n   */\n  overrides?: {\n    /**\n     * Paths the fork fully owns: never synced (existing or new).\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Local territory: upstream cannot add, modify, or delete anything under these.\n     */\n    ignored?: string[];\n\n    /**\n     * Paths pinned to the fork: the fork copy wins whole-file.\n     * Exact paths or directory prefixes, not globs: 'bench' matches 'bench/' and\n     * everything under it, 'README.md' matches that exact file.\n     * Upstream changes to a pinned file are dropped, not merged: analyze lists them under\n     * \"protected but behind upstream\" to adopt by hand.\n     * If fork deleted a pinned file, deletion is respected.\n     */\n    pinned?: string[];\n  };\n\n  /**\n   * Downstream fork repositories that cella interacts with (for upstream template repos).\n   * When configured, the 'forks' and 'contributions' services appear in the CLI menu.\n   */\n  forks?: ForkConfig[];\n}\n\n/**\n * Helper function for defining cella/cella.config.ts with type checking.\n */\nexport function defineConfig(config: CellaCliConfig): CellaCliConfig {\n  return config;\n}\n\n/**\n * Strict runtime schema mirroring {@link CellaCliConfig}.\n *\n * The TS interfaces above stay the source of truth (and keep their hover docs for\n * config authors). This schema is what's enforced at load time: `.strict()` rejects\n * unknown keys, so a typo like `ignoredFolders` for `ignored` fails closed; a silent\n * fallback would drop sync protection (tsx does not typecheck the config).\n *\n * The `satisfies z.ZodType<CellaCliConfig>` assertion keeps schema and interface in\n * lockstep: if either drifts (a renamed/removed/mis-typed field), TypeScript errors here.\n */\nexport const cellaConfigSchema = z\n  .object({\n    settings: z\n      .object({\n        upstreamUrl: z.string().min(1),\n        upstreamBranch: z.string().min(1).optional(),\n        upstreamTrack: z.enum(['release', 'branch']).optional(),\n        releaseBase: z.string().min(1).optional(),\n        packageJsonKeys: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),\n        mergePackageJson: z.boolean().optional(),\n        packageJsonSync: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),\n        syncWithPackages: z.boolean().optional(),\n        fileLinkMode: z.enum(['commit', 'file']).optional(),\n      })\n      .strict(),\n    overrides: z\n      .object({\n        ignored: z.array(z.string()).optional(),\n        pinned: z.array(z.string()).optional(),\n      })\n      .strict()\n      .optional(),\n    forks: z\n      .array(\n        z\n          .object({\n            name: z.string().min(1),\n            localPath: z.string().min(1),\n            remoteUrl: z.string().optional(),\n            pullBranch: z.string().min(1),\n          })\n          .strict(),\n      )\n      .optional(),\n  })\n  .strict() satisfies z.ZodType<CellaCliConfig>;\n\n// Internal types for the services.\n\n/** Sync services available in the CLI */\nexport type SyncService = 'analyze' | 'upgrade' | 'align' | 'audit' | 'forks' | 'contributions' | 'stats';\n\n/** Where a command shows in the menu and in `--help`; a gate shows in `--help` only, since scripts and CI run it. */\nexport type CommandGroup = 'develop' | 'security' | 'upstream' | 'gate';\n\nexport type CommandOption = [flags: string, description: string];\n\n/**\n * A command that runs without the upgrade config: no `cella.config.ts`, no override validation. It declares its own\n * options, parses them into its own shape and returns its exit code.\n */\nexport interface ToolCommand<Options = unknown> {\n  name: string;\n  group: Exclude<CommandGroup, 'upstream'>;\n  description: string;\n  /** The jobs its first operand names, the default first; the menu asks for one. Empty: the command has one job. */\n  jobs: [name: string, description: string][];\n  /**\n   * The words it takes after the job, in commander's notation such as `[scenario]` or `[paths...]`; none when unset.\n   * A command takes these or a passthrough, never both.\n   */\n  operands?: CommandOption;\n  options?: CommandOption[];\n  /** What the words after `--` are for, in `--help`. */\n  passthrough?: CommandOption;\n  parse(input: { job?: string; operands: string[]; opts: Record<string, unknown>; passthrough: string[] }): Options;\n  run(forkPath: string, options: Options): Promise<number>;\n}\n\n/** Analyze output scope for interactive and machine-readable flows */\nexport type AnalyzeScope = 'all' | 'risk' | 'protected';\n\n/** Runtime configuration with all resolved values */\nexport interface RuntimeConfig extends CellaCliConfig {\n  /** Resolved fork repository path */\n  forkPath: string;\n\n  /** Full upstream remote ref (e.g., 'cella-upstream/development') */\n  upstreamRef: string;\n\n  /** Selected sync service */\n  service: SyncService;\n\n  /** Non-interactive list output (for LLM/agent usage) */\n  list: boolean;\n\n  /** Machine-readable JSON output (for tooling/agent usage) */\n  json: boolean;\n\n  /** Scope of files returned in analyze list/json output */\n  scope?: AnalyzeScope;\n\n  /** Show verbose output */\n  verbose: boolean;\n\n  /** Pre-selected fork name (skips fork selection prompt) */\n  fork?: string;\n\n  /**\n   * Override upstream tracking for this run (analyze/upgrade), ignoring `settings.upstreamTrack`.\n   * 'branch' follows the upstream branch tip (bleeding edge); 'release' uses a release tag.\n   */\n  track?: 'release' | 'branch';\n\n  /**\n   * Pin the upstream ref for this run (analyze/upgrade), overriding `track`: a commit sha, a release\n   * tag or an upstream branch name. Must be on the upstream branch or in an upstream release.\n   */\n  ref?: string;\n\n  /**\n   * Merge with the fork's CLI config as it stands (upgrade service). Without it, a new merge stops\n   * before anything changes when upstream changed its own `overrides` or `packageJsonKeys` in ways\n   * the fork config does not follow.\n   */\n  keepConfig?: boolean;\n\n  /**\n   * Lift every pinned entry for this run (analyze, sync): managed files stay pinned, and the merge\n   * uses the full upstream history, so upstream changes that earlier syncs dropped come back too.\n   */\n  unpinned?: boolean;\n\n  /** Count what the current branch changed since it left this ref, by kind of file (stats service) */\n  since?: string;\n\n  /** Print the `since` table as markdown for a pull request description (stats service) */\n  md?: boolean;\n\n  /** List every file instead of collapsing large groups (analyze), or every upstream alignment (align) */\n  all?: boolean;\n\n  /** Print one alignment's README (align service) */\n  show?: string;\n\n  /** Write one alignment's folder where its codemod can run (align service) */\n  extract?: string;\n\n  /** Run one alignment's codemod, keeping files identical to upstream as they are (align service) */\n  run?: string;\n\n  /** Arguments after `--`, passed to the codemod as given (align service, with `run`) */\n  runArgs?: string[];\n\n  /** Alignment ids to record as handled (align service) */\n  mark?: string[];\n}\n\n/** File status after analysis */\nexport type FileStatus =\n  | 'identical' // No changes needed\n  | 'ahead' // Fork is ahead, protected (pinned/ignored)\n  | 'local' // Local file (never existed upstream)\n  | 'drifted' // Fork is ahead, NOT protected (at risk)\n  | 'behind' // Upstream has changes to sync\n  | 'diverged' // Both changed, will merge\n  | 'pinned' // Fork wins on conflict\n  | 'ignored' // Excluded from sync entirely\n  | 'deleted' // Fork deleted, will stay deleted\n  | 'renamed'; // Upstream renamed file\n\n/** Statuses the sync applies changes for: a staged sync holds at least one file with one of these. */\nexport const SYNC_APPLIED_STATUSES: readonly FileStatus[] = ['behind', 'diverged', 'renamed', 'ignored', 'pinned'];\n\n/** Commit metadata for a single log entry */\nexport interface CommitRangeEntry {\n  hash: string;\n  message: string;\n  date: string;\n  /** Unix epoch seconds of the commit */\n  timestamp?: number;\n}\n\n/** Analyzed file with status and metadata */\nexport interface AnalyzedFile {\n  path: string;\n  status: FileStatus;\n  /** True if file is in ignored list */\n  isIgnored: boolean;\n  /** True if file is in pinned list */\n  isPinned: boolean;\n  /** True if file exists in fork */\n  existsInFork: boolean;\n  /** True if file exists in upstream */\n  existsInUpstream: boolean;\n  /** Relative date when file was last changed (since merge-base) */\n  changedAt?: string;\n  /** Unix epoch seconds of the last change, for sorting */\n  changedTs?: number;\n  /** Short commit hash of the last change */\n  changedCommit?: string;\n  /** For diverged files: relative date of upstream change */\n  upstreamChangedAt?: string;\n  /** For diverged files: Unix epoch seconds of the upstream change, for sorting */\n  upstreamChangedTs?: number;\n  /** For diverged files: short commit hash of the upstream change */\n  upstreamCommit?: string;\n  /** For renamed files: the original path before rename */\n  renamedFrom?: string;\n  /**\n   * Protected (pinned/ignored) files only: both sides changed since the merge-base. The fork\n   * side wins whole-file, so upstream's changes to this path are dropped by the sync.\n   */\n  upstreamChanged?: boolean;\n  /** For `upstreamChanged` and `upstreamOnly` files: lines upstream changed since the merge-base (undefined for binary) */\n  upstreamChangedLines?: number;\n  /**\n   * Ignored files only: upstream changed, added or deleted the file since the merge-base and the\n   * fork did not touch it. Ignored paths never sync, so without this flag the change stays unseen\n   * (new config keys, version bumps). Managed files and generated output (`isGeneratedFile`) are\n   * never flagged.\n   */\n  upstreamOnly?: boolean;\n  /**\n   * Pinned `ahead` files only: lines present upstream but absent from the fork (undefined for\n   * binary). Independent of the sync point, so it also shows upstream content dropped by an\n   * earlier sync, or removed on purpose; only a diff can tell.\n   */\n  upstreamLinesAbsent?: number;\n}\n\n/** Summary counts by status */\nexport interface AnalysisSummary {\n  /** Changed package/config files that are handled separately from normal sync categories */\n  managed: number;\n  identical: number;\n  ahead: number;\n  local: number;\n  drifted: number;\n  behind: number;\n  diverged: number;\n  pinned: number;\n  ignored: number;\n  deleted: number;\n  renamed: number;\n}\n\n/** Merge result from merge-engine */\nexport interface MergeResult {\n  success: boolean;\n  /** Upstream branch name for file links */\n  upstreamBranch?: string;\n  /** Resolved concrete upstream ref that was merged (branch ref or release tag ref) */\n  upstreamRef?: string;\n  /** Upstream release tag synced (when tracking releases) */\n  upstreamTag?: string;\n  files: AnalyzedFile[];\n  summary: AnalysisSummary;\n  conflicts: string[];\n  /** Upstream GitHub URL base for commit links */\n  upstreamGitHubUrl?: string;\n  /** Upstream commit info */\n  upstreamCommit?: CommitRangeEntry;\n  /** Upstream commits since the last sync point */\n  upstreamCommitCount?: number;\n  /** Files that were auto-merged by git (diverged without remaining conflicts) */\n  autoMergedFiles?: string[];\n  /**\n   * Protected (pinned/ignored) files resolved to the fork side although upstream also changed\n   * them: upstream's hunks were dropped, not merged. Review each against upstream.\n   */\n  protectedConflicts?: string[];\n  /** `<merge-base>..<upstream>` range of short SHAs: what upstream changed since the last sync, for the review page. */\n  upstreamDiffRange?: string;\n  /** How upstream's own CLI config changed since the merge-base, where the fork config does not follow. */\n  upstreamOverrides?: UpstreamOverridesReport;\n  /** Files flagged `upstreamOnly`, grouped by the `ignored` entry they fall under (config order). */\n  ignoredUpstreamChanges?: IgnoredUpstreamGroup[];\n  /**\n   * Upstream alignments: how many the incoming ref holds, which ones upstream added since the\n   * sync point, and the ones open in the fork after the run. A sync opens the arrivals; a dry run\n   * leaves them out of `open`.\n   */\n  alignments?: { total: number; arrived: string[]; open: string[] };\n}\n\n/** Entries of one CLI config list (`pinned`, `ignored` or `packageJsonKeys`) that the fork config does not mirror. */\nexport interface OverrideListChanges {\n  /** Entries upstream added since the merge-base that the fork list lacks. */\n  added: string[];\n  /** Entries upstream removed since the merge-base that the fork list still carries. */\n  removed: string[];\n  /** Entries upstream renamed that the fork never carried under either path: informational, never a stop. */\n  moved?: { from: string; to: string }[];\n}\n\n/**\n * Upstream CLI config changes the fork should review. The CLI config is managed (never merged),\n * so new upstream `pinned`/`ignored` entries and `packageJsonKeys` only reach the fork by\n * hand. `unreadable` means upstream's config was missing or unparsable at one side (`base` =\n * merge-base, `incoming` = upstream ref), so nothing was compared.\n */\nexport type UpstreamOverridesReport =\n  | {\n      kind: 'changes';\n      pinned: OverrideListChanges;\n      ignored: OverrideListChanges;\n      packageJsonKeys: OverrideListChanges;\n    }\n  | { kind: 'unreadable'; side: 'base' | 'incoming' };\n\n/** Upstream-only changes under one `ignored` entry. */\nexport interface IgnoredUpstreamGroup {\n  /** The `ignored` entry (configured or derived from an app-owned module) the files fall under. */\n  entry: string;\n  /** Changed paths under the entry, sorted. */\n  paths: string[];\n  /** Paths the fork lacks (new upstream files). */\n  added: number;\n  /** Paths upstream deleted (the fork keeps them). */\n  deleted: number;\n}\n"],"mappings":";AAKA,SAAS,SAAS;AAIlB,IAAM,oBAAoB;AAAA,EACxB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAqHO,SAAS,aAAa,QAAwC;AACnE,SAAO;AACT;AAaO,IAAM,oBAAoB,EAC9B,OAAO;AAAA,EACN,UAAU,EACP,OAAO;AAAA,IACN,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC7B,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IAC3C,eAAe,EAAE,KAAK,CAAC,WAAW,QAAQ,CAAC,EAAE,SAAS;AAAA,IACtD,aAAa,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IACxC,iBAAiB,EAAE,MAAM,EAAE,KAAK,iBAAiB,CAAC,EAAE,SAAS;AAAA,IAC7D,kBAAkB,EAAE,QAAQ,EAAE,SAAS;AAAA,IACvC,iBAAiB,EAAE,MAAM,EAAE,KAAK,iBAAiB,CAAC,EAAE,SAAS;AAAA,IAC7D,kBAAkB,EAAE,QAAQ,EAAE,SAAS;AAAA,IACvC,cAAc,EAAE,KAAK,CAAC,UAAU,MAAM,CAAC,EAAE,SAAS;AAAA,EACpD,CAAC,EACA,OAAO;AAAA,EACV,WAAW,EACR,OAAO;AAAA,IACN,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,IACtC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EACvC,CAAC,EACA,OAAO,EACP,SAAS;AAAA,EACZ,OAAO,EACJ;AAAA,IACC,EACG,OAAO;AAAA,MACN,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MACtB,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,MAC3B,WAAW,EAAE,OAAO,EAAE,SAAS;AAAA,MAC/B,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC;AAAA,IAC9B,CAAC,EACA,OAAO;AAAA,EACZ,EACC,SAAS;AACd,CAAC,EACA,OAAO;","names":[]}

package/dist/index.js

@@ -234,7 +234,7 @@ import process6 from "process";
 // package.json
 var package_default = {
   name: "@cellajs/cli",
-  version: "0.6.6",
+  version: "0.6.7",
   private: false,
   license: "MIT",
   description: "CLI for managing your monorepo and upgrading it with upstream Cella.",
@@ -1319,6 +1319,9 @@ function printUpstreamOverrideChanges(result) {
     for (const entry of report[list2].removed) {
       lines.push(`  ${colors_default.red("\u2212")} ${list2}: ${entry}${colors_default.dim(" \xB7 dropped upstream, still in your config")}`);
     }
+    for (const { from, to } of report[list2].moved ?? []) {
+      lines.push(colors_default.dim(`  ~ ${list2}: ${from} \u2192 ${to} \xB7 renamed upstream, your config never had it`));
+    }
   }
   console.info(
     `${warningMark} ${colors_default.yellow(`upstream changed its CLI config \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
@@ -1403,8 +1406,8 @@ async function resolveTestbed(forkPath, data = "seed") {
     throw new Error("shared/src/local-database.ts names no testbed database: upgrade the app from cella first");
   }
   const composeEnv = databases.composeEnv();
-  const envFile = join4(forkPath, "backend/.env");
-  const fileEnv = existsSync4(envFile) ? parseEnv(readFileSync2(envFile, "utf8")) : {};
+  const envFile = [join4(forkPath, ".env"), join4(forkPath, "backend/.env")].find((path) => existsSync4(path));
+  const fileEnv = envFile ? parseEnv(readFileSync2(envFile, "utf8")) : {};
   const portOffset = facts.devPortOffset + PORT_SHIFT;
   return {
     forkPath,
@@ -1413,7 +1416,7 @@ async function resolveTestbed(forkPath, data = "seed") {
     databasePort,
     portOffset,
     env: {
-      // The seed creates the admin that backend/.env names, and a command signs in as that user
+      // The seed creates the admin that the env file names, and a command signs in as that user
       ...fileEnv.ADMIN_EMAIL ? { ADMIN_EMAIL: fileEnv.ADMIN_EMAIL } : {},
       ...getEnvSnapshot(),
       ...data === "showcase" ? { ADMIN_EMAIL: showcaseAdmin(forkPath) } : {},
@@ -3324,7 +3327,7 @@ var seconds = (since) => `${((Date.now() - since) / 1e3).toFixed(1)}s`;
 async function runAudit(run, scope, testbed, options) {
   const startedAt = Date.now();
   const email = options.email ?? testbed.env.ADMIN_EMAIL;
-  if (!email) throw new Error("no audit user: pass --email, or set ADMIN_EMAIL in backend/.env");
+  if (!email) throw new Error("no audit user: pass --email, or set ADMIN_EMAIL in .env");
   const builtAt = statSync(join10(run.forkPath, "frontend/dist/index.html"), { throwIfNoEntry: false })?.mtime;
   printStep("auditing", `${testbed.frontendUrl}, frontend build of ${builtAt?.toLocaleString() ?? "unknown date"}`);
   const states = options.states.length > 0 ? scope.states.filter((state) => options.states.includes(state.id)) : scope.states;
@@ -3722,7 +3725,7 @@ var a11yCommand = {
   options: [
     ["--states <ids>", "audit: these states only, comma separated; writes ledger-partial.json, never the ledger"],
     ["--workers <n>", "audit: states audited at the same time (default 4)"],
-    ["--email <address>", "audit: the audit user (default ADMIN_EMAIL in backend/.env)"],
+    ["--email <address>", "audit: the audit user (default ADMIN_EMAIL in .env)"],
     ["--publish", "report: put the PDF where the app serves it and print what the statement needs"],
     ["--draft", "report: publish while rows still need a person; the statement calls the results provisional"],
     ["--file <path>", "decide: a JSON list of decisions"],
@@ -5406,7 +5409,7 @@ async function spinnersGone(page, quiet = 1e3, cap = 45e3) {
 var hasMfaScript = (forkPath) => Boolean(JSON.parse(readFileSync13(join21(forkPath, "backend/package.json"), "utf8")).scripts?.["showcase:mfa"]);
 async function shoot(forkPath, list2, testbed, options) {
   const email = options.email ?? testbed.env.ADMIN_EMAIL;
-  if (!email) throw new Error("no shot user: pass --email, or set ADMIN_EMAIL in backend/.env");
+  if (!email) throw new Error("no shot user: pass --email, or set ADMIN_EMAIL in .env");
   const todo = options.ids.length > 0 ? list2.shots.filter((shot2) => options.ids.includes(shot2.id)) : list2.shots;
   const user = mintSession(email, { forkPath, env: testbed.env });
   const scratch = mkdtempSync(join21(tmpdir(), "cella-screenshots-"));
@@ -5535,7 +5538,7 @@ var screenshotsCommand = {
   operands: ["[ids...]", "the shots to take (default: all)"],
   options: [
     ["--out <dir>", "write into this folder, a trial run that leaves the working tree alone"],
-    ["--email <address>", "the shot user (default the showcase admin, else ADMIN_EMAIL in backend/.env)"]
+    ["--email <address>", "the shot user (default the showcase admin, else ADMIN_EMAIL in .env)"]
   ],
   parse: ({ operands, opts }) => ({
     ids: operands,
@@ -7052,13 +7055,27 @@ function parseOverrideLists(source) {
   }
 }
 function diffOverrideLists(base, incoming, fork) {
+  const basenameOf2 = (entry) => entry.slice(entry.lastIndexOf("/") + 1);
   const diff = (key) => {
     const baseSet = new Set(base[key].map(normalizeEntry).filter(Boolean));
     const incomingSet = new Set(incoming[key].map(normalizeEntry).filter(Boolean));
     const forkEntries = fork[key].map(normalizeEntry).filter(Boolean);
+    const newEntries = [...incomingSet].filter((entry) => !baseSet.has(entry) && !isUnderAnyFolder(entry, forkEntries));
+    const renameSources = [...baseSet].filter(
+      (entry) => !incomingSet.has(entry) && !forkEntries.includes(entry) && !isUnderAnyFolder(entry, forkEntries)
+    );
+    const moved = [];
+    const added = newEntries.filter((entry) => {
+      const sourceAt = renameSources.findIndex((source) => basenameOf2(source) === basenameOf2(entry));
+      if (sourceAt === -1) return true;
+      moved.push({ from: renameSources[sourceAt], to: entry });
+      renameSources.splice(sourceAt, 1);
+      return false;
+    });
     return {
-      added: [...incomingSet].filter((entry) => !baseSet.has(entry) && !isUnderAnyFolder(entry, forkEntries)),
-      removed: [...baseSet].filter((entry) => !incomingSet.has(entry) && forkEntries.includes(entry))
+      added,
+      removed: [...baseSet].filter((entry) => !incomingSet.has(entry) && forkEntries.includes(entry)),
+      ...moved.length > 0 ? { moved } : {}
     };
   };
   const diffKeys = () => {
@@ -7086,9 +7103,17 @@ async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, for
     packageJsonKeys: forkConfig.settings.packageJsonKeys ?? DEFAULT_PACKAGE_JSON_KEYS
   };
   const changes = diffOverrideLists(base, incoming, fork);
-  const count3 = Object.values(changes).reduce((n, list2) => n + list2.added.length + list2.removed.length, 0);
+  const count3 = Object.values(changes).reduce(
+    (n, list2) => n + list2.added.length + list2.removed.length + (list2.moved?.length ?? 0),
+    0
+  );
   return count3 > 0 ? { kind: "changes", ...changes } : void 0;
 }
+function hasBlockingOverrideChanges(report) {
+  if (report.kind !== "changes") return false;
+  const lists = [report.pinned, report.ignored, report.packageJsonKeys];
+  return lists.some((list2) => list2.added.length > 0 || list2.removed.length > 0);
+}
 
 // src/utils/overrides.ts
 function normalizeEntry(entry) {
@@ -7137,8 +7162,9 @@ async function validateOverrides(config, forkPath, upstreamRef) {
     const path = normalizeEntry(entry);
     const ignoredEntry = ignored.find((folder) => isUnderAnyFolder(path, [folder]));
     if (/[*?]/.test(entry)) warnings.push(`pin uses glob (not supported, use a path or folder): ${entry}`);
-    else if (!existsSync21(join28(forkPath, path))) warnings.push(`pin not found: ${entry}`);
-    else if (ignoredEntry) warnings.push(`pin does nothing, '${normalizeEntry(ignoredEntry)}' is ignored: ${entry}`);
+    else if (!existsSync21(join28(forkPath, path))) {
+      if (!upstream || !await fileExistsAtRef(forkPath, upstream, path)) warnings.push(`pin not found: ${entry}`);
+    } else if (ignoredEntry) warnings.push(`pin does nothing, '${normalizeEntry(ignoredEntry)}' is ignored: ${entry}`);
     else if (!upstream) continue;
     else if (await fileExistsAtRef(forkPath, upstream, path)) pinsUpstreamHas.push(entry);
     else warnings.push(`pin does nothing, upstream no longer has it: ${entry}`);
@@ -7159,6 +7185,7 @@ async function validateOverrides(config, forkPath, upstreamRef) {
       warnings.push(`ignored entry uses glob (not supported, use a path or folder): ${entry}`);
     } else if (!existsSync21(join28(forkPath, path))) {
       if (upstreamRef && await fileExistsAtRef(forkPath, upstreamRef, path)) continue;
+      if (isGeneratedFile(path)) continue;
       warnings.push(`ignored entry not found: ${entry}`);
     }
   }
@@ -7489,6 +7516,109 @@ import { existsSync as existsSync22 } from "fs";
 import { rm as rm2 } from "fs/promises";
 import { join as join29 } from "path";
 
+// src/utils/audit-utils.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
+function outdatedPackageName(key) {
+  const name = key.split(" ")[0];
+  const at = name.indexOf("@", 1);
+  return at === -1 ? name : name.slice(0, at);
+}
+function getRepoUrl(repositoryUrl) {
+  if (!repositoryUrl) return null;
+  let url = repositoryUrl;
+  if (url.startsWith("git+")) {
+    url = url.slice(4);
+  }
+  if (url.endsWith(".git")) {
+    url = url.slice(0, -4);
+  }
+  if (url.startsWith("git://")) {
+    url = url.replace("git://", "https://");
+  }
+  return url;
+}
+function isGitHubRepoUrl(repoUrl) {
+  if (!repoUrl) return false;
+  try {
+    const parsed2 = new URL(repoUrl);
+    return parsed2.hostname === "github.com" || parsed2.hostname === "www.github.com";
+  } catch {
+    return false;
+  }
+}
+function getReleasesUrl(repoUrl) {
+  if (!isGitHubRepoUrl(repoUrl)) return null;
+  return `${repoUrl}/releases`;
+}
+async function runPnpm(args, cwd) {
+  try {
+    const { stdout, stderr } = await execFileAsync2("pnpm", args, {
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024,
+      cwd
+    });
+    return { ok: true, stdout, stderr };
+  } catch (error) {
+    const { stdout = "", stderr = "" } = error;
+    return { ok: false, stdout, stderr: stdout || stderr ? stderr : String(error) };
+  }
+}
+async function runPnpmJson(args, cwd) {
+  try {
+    return JSON.parse((await runPnpm([...args, "--loglevel=error"], cwd)).stdout);
+  } catch {
+    return null;
+  }
+}
+async function runPnpmAudit(cwd) {
+  const result = await runPnpmJson(["audit", "--json"], cwd);
+  if (!result || typeof result.advisories !== "object" || result.advisories === null) return null;
+  return result;
+}
+async function readReleaseAgeMinutes(cwd) {
+  const minutes = Number.parseInt((await runPnpm(["config", "get", "minimumReleaseAge"], cwd)).stdout, 10);
+  return Number.isNaN(minutes) ? 0 : minutes;
+}
+async function fetchPublishTimes(name, cwd) {
+  const times = await runPnpmJson(["view", name, "time", "--json"], cwd);
+  return times && typeof times === "object" && !("error" in times) ? times : null;
+}
+function editJsonText(content, change) {
+  const json = JSON.parse(content);
+  change(json);
+  const indent = content.match(/^[ \t]+(?=")/m)?.[0] ?? "  ";
+  return `${JSON.stringify(json, null, indent)}${content.endsWith("\n") ? "\n" : ""}`;
+}
+function rewriteSpecifier(spec, latest) {
+  const match = spec.match(/^([\^~]?)\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?$/);
+  return match ? `${match[1]}${latest}` : null;
+}
+var vulnIcons = {
+  critical: colors_default.red("\u25CF"),
+  high: colors_default.red("\u25CF"),
+  moderate: colors_default.yellow("\u25CF"),
+  low: colors_default.blue("\u25CF"),
+  info: colors_default.gray("\u25CF")
+};
+function getVulnIcon(severity) {
+  return vulnIcons[severity] ?? colors_default.gray("\u25CF");
+}
+function middleTruncate(str2, maxLen) {
+  if (str2.length <= maxLen) return str2;
+  const ellipsis = "\u2026";
+  const charsToShow = maxLen - ellipsis.length;
+  const frontChars = Math.ceil(charsToShow / 2);
+  const backChars = Math.floor(charsToShow / 2);
+  return str2.slice(0, frontChars) + ellipsis + str2.slice(-backChars);
+}
+function formatDependents(dependents) {
+  if (dependents.length === 0) return "";
+  if (dependents.length === 1) return dependents[0];
+  return `${dependents[0]} +${dependents.length - 1}`;
+}
+
 // src/utils/versions.ts
 function parseComparableVersion(version) {
   const trimmed = version.trim();
@@ -7552,6 +7682,10 @@ async function readUpstreamCliRange(repoPath, ref) {
     return null;
   }
 }
+function releaseAgeExcludeHint(range) {
+  const version = range.match(/\d+\S*/)?.[0] ?? range;
+  return `  pnpm delays fresh releases (minimumReleaseAge): if the install is refused, add '${CLI_PACKAGE}@${version}' to minimumReleaseAgeExclude in pnpm-workspace.yaml.`;
+}
 function cliVersionMismatch(running, range) {
   if (/^\s*(<|>(?!=))/.test(range)) return null;
   const required = parseComparableVersion(range);
@@ -7567,6 +7701,81 @@ function cliVersionMismatch(running, range) {
 function isReportableIgnored(filePath) {
   return !isManagedFile(filePath) && !isGeneratedFile(filePath);
 }
+var basenameOf = (path) => path.slice(path.lastIndexOf("/") + 1);
+var dirnameOf = (path) => path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+function directoryMoves(changes) {
+  const votes = /* @__PURE__ */ new Map();
+  for (const [newPath, change] of changes) {
+    if (change.status !== "R" || !change.oldPath || basenameOf(change.oldPath) !== basenameOf(newPath)) continue;
+    const from = dirnameOf(change.oldPath);
+    const counts = votes.get(from) ?? /* @__PURE__ */ new Map();
+    counts.set(dirnameOf(newPath), (counts.get(dirnameOf(newPath)) ?? 0) + 1);
+    votes.set(from, counts);
+  }
+  const moves = /* @__PURE__ */ new Map();
+  for (const [from, counts] of votes) {
+    const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    if (ranked.length === 1 || ranked[0][1] > ranked[1][1]) moves.set(from, ranked[0][0]);
+  }
+  return moves;
+}
+var joinDir = (dir, name) => dir ? `${dir}/${name}` : name;
+function repairIncomingRenames(changes, context) {
+  const dirMoves = directoryMoves(changes);
+  const snapshot = new Map(changes);
+  const crossed = [];
+  const keptTargets = /* @__PURE__ */ new Set();
+  const renameSources = /* @__PURE__ */ new Set();
+  for (const [newPath, change] of changes) {
+    if (change.status !== "R" || !change.oldPath) continue;
+    renameSources.add(change.oldPath);
+    if (basenameOf(change.oldPath) === basenameOf(newPath)) keptTargets.add(newPath);
+    else crossed.push({ from: newPath, oldPath: change.oldPath, change });
+  }
+  const desired = /* @__PURE__ */ new Map();
+  for (const pair of crossed) {
+    const name = basenameOf(pair.oldPath);
+    const mappedDir = dirMoves.get(dirnameOf(pair.oldPath));
+    const candidates = [
+      ...mappedDir === void 0 ? [] : [joinDir(mappedDir, name)],
+      joinDir(dirnameOf(pair.from), name)
+    ];
+    const target = candidates.find(
+      (path) => context.incomingPaths.has(path) && !context.basePaths.has(path) && !keptTargets.has(path)
+    );
+    desired.set(pair.from, target ?? pair.from);
+  }
+  const targets = [...desired.values()];
+  if (new Set(targets).size === targets.length) {
+    const targetSet = new Set(targets);
+    for (const pair of crossed) {
+      const target = desired.get(pair.from);
+      if (target === pair.from) continue;
+      changes.set(target, {
+        status: "R",
+        oldPath: pair.oldPath,
+        baseHash: pair.change.baseHash,
+        targetHash: snapshot.get(target)?.targetHash ?? null
+      });
+    }
+    for (const pair of crossed) {
+      if (desired.get(pair.from) === pair.from || targetSet.has(pair.from)) continue;
+      changes.set(pair.from, { status: "A", baseHash: null, targetHash: snapshot.get(pair.from)?.targetHash ?? null });
+    }
+  }
+  for (const oldPath of context.localPaths) {
+    if (context.incomingPaths.has(oldPath) || !context.basePaths.has(oldPath)) continue;
+    if (renameSources.has(oldPath) || !context.isProtected(oldPath)) continue;
+    const mappedDir = dirMoves.get(dirnameOf(oldPath));
+    if (mappedDir === void 0) continue;
+    const target = joinDir(mappedDir, basenameOf(oldPath));
+    if (!context.incomingPaths.has(target) || context.basePaths.has(target) || changes.get(target)?.status !== "A")
+      continue;
+    changes.set(target, { status: "R", oldPath, baseHash: null, targetHash: changes.get(target)?.targetHash ?? null });
+    changes.delete(oldPath);
+    renameSources.add(oldPath);
+  }
+}
 async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predicates, onProgress) {
   onProgress?.("collecting file hashes (batch)...");
   const [forkHashes, upstreamHashes, baseHashes] = await Promise.all([
@@ -7576,6 +7785,12 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
   ]);
   const upstreamChanges = await getFileChanges(repoPath, mergeBaseRef, incomingRef);
   const forkChanges = await getFileChanges(repoPath, mergeBaseRef, localRef);
+  repairIncomingRenames(upstreamChanges, {
+    basePaths: new Set(baseHashes.keys()),
+    incomingPaths: new Set(upstreamHashes.keys()),
+    localPaths: new Set(forkHashes.keys()),
+    isProtected: (path) => predicates.isIgnored(path) || predicates.isPinned(path)
+  });
   const upstreamRenames = /* @__PURE__ */ new Map();
   for (const [newPath, change] of upstreamChanges) {
     if (change.status === "R" && change.oldPath) {
@@ -7660,7 +7875,7 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
       status = "ignored";
     } else if (!inFork && inUpstream) {
       const locallyDeleted = baseHash !== null && upstreamHash === baseHash;
-      status = fileIsPinned || locallyDeleted ? "deleted" : "behind";
+      status = fileIsPinned && baseHash !== null || locallyDeleted ? "deleted" : "behind";
     } else if (inFork && !inUpstream) {
       if (baseHash !== null) {
         status = fileIsPinned ? "ahead" : "behind";
@@ -7772,6 +7987,9 @@ async function readOriginGitHubUrl(forkPath) {
 function isProtectedFile(file) {
   return file.isIgnored || file.isPinned;
 }
+function isPinnedFirstArrival(file) {
+  return file.isPinned && !file.isIgnored && !file.existsInFork && file.existsInUpstream && file.status === "behind";
+}
 function syncPredicates(config) {
   return {
     isIgnored: (path) => isIgnored(path, config),
@@ -7792,7 +8010,7 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
   const batchRemovePaths = [];
   const movedProtected = [];
   for (const file of analyzedFiles) {
-    if (file.status === "identical" || file.status === "ahead") continue;
+    if (file.status === "identical" || file.status === "ahead" || isPinnedFirstArrival(file)) continue;
     if (file.status === "pinned" && file.renamedFrom) movedProtected.push({ from: file.renamedFrom, to: file.path });
     else if (file.isIgnored || file.isPinned) {
       (file.existsInFork ? batchRestorePaths : batchRemovePaths).push(file.path);
@@ -7817,14 +8035,17 @@ async function applyDirectMerge(forkPath, upstreamRef, mergeBaseRef, config, onP
   }
   for (const file of analyzedFiles) {
     const { path: filePath, status, existsInFork } = file;
-    if (status === "identical" || status === "ahead" || isProtectedFile(file)) continue;
+    if (status === "identical" || status === "ahead" || isProtectedFile(file) && !isPinnedFirstArrival(file))
+      continue;
     if (status === "diverged") {
       onProgress?.(`\u2192 ${filePath}: using git merge result (diverged)`);
       continue;
     }
     if (status === "behind") {
       if (!existsInFork) {
-        onProgress?.(`\u2192 ${filePath}: adding from upstream (new file)`);
+        onProgress?.(
+          `\u2192 ${filePath}: adding from upstream (${isPinnedFirstArrival(file) ? "pinned, upstream's copy is your first" : "new file"})`
+        );
         await checkoutFromRef(forkPath, upstreamRef, [filePath]);
       } else if (!file.existsInUpstream) {
         onProgress?.(`\u2192 ${filePath}: removing (deleted in upstream)`);
@@ -7963,7 +8184,11 @@ async function prepareUpstream(config, onProgress, onStep) {
   config.upstreamRef = upstreamRef;
   const cliRange = await readUpstreamCliRange(forkPath, upstreamRef);
   const cliMismatch = cliRange ? cliVersionMismatch(VERSION, cliRange) : null;
-  if (cliMismatch) throw new Error(cliMismatch);
+  if (cliMismatch && cliRange) {
+    const delayed = await readReleaseAgeMinutes(forkPath) > 0;
+    throw new Error(delayed ? `${cliMismatch}
+${releaseAgeExcludeHint(cliRange)}` : cliMismatch);
+  }
   onProgress?.("checking sync base...");
   await ensureSyncBase(forkPath, "HEAD", upstreamRef);
   const upstreamGitHubUrl = getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0;
@@ -8006,7 +8231,7 @@ async function assertSyncConfigFollowed(config, ctx) {
   const report = await compareUpstreamOverrides(config.forkPath, ctx.mergeBase, ctx.upstreamRef, config).catch(
     () => void 0
   );
-  if (report?.kind === "changes") throw new UpstreamConfigChangedError(report);
+  if (report && hasBlockingOverrideChanges(report)) throw new UpstreamConfigChangedError(report);
 }
 function resultMeta(config, ctx) {
   return {
@@ -9069,109 +9294,6 @@ import { readFileSync as readFileSync19 } from "fs";
 import { basename as basename9, join as join35, relative as relative4 } from "path";
 import { checkbox, Separator } from "@inquirer/prompts";
 
-// src/utils/audit-utils.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
-function outdatedPackageName(key) {
-  const name = key.split(" ")[0];
-  const at = name.indexOf("@", 1);
-  return at === -1 ? name : name.slice(0, at);
-}
-function getRepoUrl(repositoryUrl) {
-  if (!repositoryUrl) return null;
-  let url = repositoryUrl;
-  if (url.startsWith("git+")) {
-    url = url.slice(4);
-  }
-  if (url.endsWith(".git")) {
-    url = url.slice(0, -4);
-  }
-  if (url.startsWith("git://")) {
-    url = url.replace("git://", "https://");
-  }
-  return url;
-}
-function isGitHubRepoUrl(repoUrl) {
-  if (!repoUrl) return false;
-  try {
-    const parsed2 = new URL(repoUrl);
-    return parsed2.hostname === "github.com" || parsed2.hostname === "www.github.com";
-  } catch {
-    return false;
-  }
-}
-function getReleasesUrl(repoUrl) {
-  if (!isGitHubRepoUrl(repoUrl)) return null;
-  return `${repoUrl}/releases`;
-}
-async function runPnpm(args, cwd) {
-  try {
-    const { stdout, stderr } = await execFileAsync2("pnpm", args, {
-      encoding: "utf8",
-      maxBuffer: 10 * 1024 * 1024,
-      cwd
-    });
-    return { ok: true, stdout, stderr };
-  } catch (error) {
-    const { stdout = "", stderr = "" } = error;
-    return { ok: false, stdout, stderr: stdout || stderr ? stderr : String(error) };
-  }
-}
-async function runPnpmJson(args, cwd) {
-  try {
-    return JSON.parse((await runPnpm([...args, "--loglevel=error"], cwd)).stdout);
-  } catch {
-    return null;
-  }
-}
-async function runPnpmAudit(cwd) {
-  const result = await runPnpmJson(["audit", "--json"], cwd);
-  if (!result || typeof result.advisories !== "object" || result.advisories === null) return null;
-  return result;
-}
-async function readReleaseAgeMinutes(cwd) {
-  const minutes = Number.parseInt((await runPnpm(["config", "get", "minimumReleaseAge"], cwd)).stdout, 10);
-  return Number.isNaN(minutes) ? 0 : minutes;
-}
-async function fetchPublishTimes(name, cwd) {
-  const times = await runPnpmJson(["view", name, "time", "--json"], cwd);
-  return times && typeof times === "object" && !("error" in times) ? times : null;
-}
-function editJsonText(content, change) {
-  const json = JSON.parse(content);
-  change(json);
-  const indent = content.match(/^[ \t]+(?=")/m)?.[0] ?? "  ";
-  return `${JSON.stringify(json, null, indent)}${content.endsWith("\n") ? "\n" : ""}`;
-}
-function rewriteSpecifier(spec, latest) {
-  const match = spec.match(/^([\^~]?)\d+(?:\.\d+){0,2}(?:-[0-9A-Za-z.-]+)?$/);
-  return match ? `${match[1]}${latest}` : null;
-}
-var vulnIcons = {
-  critical: colors_default.red("\u25CF"),
-  high: colors_default.red("\u25CF"),
-  moderate: colors_default.yellow("\u25CF"),
-  low: colors_default.blue("\u25CF"),
-  info: colors_default.gray("\u25CF")
-};
-function getVulnIcon(severity) {
-  return vulnIcons[severity] ?? colors_default.gray("\u25CF");
-}
-function middleTruncate(str2, maxLen) {
-  if (str2.length <= maxLen) return str2;
-  const ellipsis = "\u2026";
-  const charsToShow = maxLen - ellipsis.length;
-  const frontChars = Math.ceil(charsToShow / 2);
-  const backChars = Math.floor(charsToShow / 2);
-  return str2.slice(0, frontChars) + ellipsis + str2.slice(-backChars);
-}
-function formatDependents(dependents) {
-  if (dependents.length === 0) return "";
-  if (dependents.length === 1) return dependents[0];
-  return `${dependents[0]} +${dependents.length - 1}`;
-}
-
 // src/utils/local-tools.ts
 import { execFile as execFile3 } from "child_process";
 import { existsSync as existsSync24, realpathSync as realpathSync2 } from "fs";
@@ -10921,9 +11043,18 @@ function readSearchable(filePath) {
     return "";
   }
 }
+var codeFilePattern = /\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
+var proseFilePattern = /\.(?:md|mdx|markdown)$/i;
+function stripComments(text2) {
+  return text2.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
 function fileSource(forkPath, path) {
   let text2;
-  return { path, label: path, text: () => text2 ??= readSearchable(join37(forkPath, path)) };
+  const read = () => {
+    const content = readSearchable(join37(forkPath, path));
+    return codeFilePattern.test(path) ? stripComments(content) : content;
+  };
+  return { path, label: path, text: () => text2 ??= read() };
 }
 async function readScriptsAtRef(forkPath, ref, path) {
   try {
@@ -10976,7 +11107,7 @@ async function loadForkUsage(forkPath, upstreamRef, baseRef) {
   const sources = [];
   for (const path of diff.split("\0").filter(Boolean)) {
     if (isPackageJson(path)) sources.push(...await scriptSources(forkPath, upstreamRef, baseRef, path));
-    else if (!isManagedFile(path)) sources.push(fileSource(forkPath, path));
+    else if (!isManagedFile(path) && !proseFilePattern.test(path)) sources.push(fileSource(forkPath, path));
   }
   const findIn = (scoped, patterns) => scoped.find((source) => patterns.some((pattern) => pattern.test(source.text())))?.label;
   return {