@chatcode/cco-market 1.45.1

package/src/snapshot.ts

@@ -0,0 +1,532 @@
+/**
+ * Profile snapshots — issue #98 (phase 3), implementing the snapshot half of
+ * #19: before any ordering / preset change is applied, the profile's
+ * composition-critical files are captured as a timestamped snapshot; a failed
+ * or unwanted change can be rolled back in one step.
+ *
+ * A snapshot is a single JSON document under `<profile>/.dsh-market/
+ * snapshots/<timestamp>-<seq>.json` describing the files that define the
+ * profile's composition: package.json (dependency + bundle list),
+ * cordis.patch.yml (the user patch layer) and state.json (market disable
+ * list + groups). Version 2 records optional-file absence explicitly;
+ * restoring validates every path, reconciles writes and deletions, and rolls
+ * completed actions back if a later action fails.
+ *
+ * Retention: after every create, snapshots are pruned to the most recent
+ * `maxSnapshots` (default 20); the cap is configurable through the market
+ * plugin config (`maxSnapshots`) and each snapshot can also be deleted
+ * individually from the UI.
+ */
+
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { logEvent } from './log.ts'
+
+const SNAPSHOT_DIR = join('.dsh-market', 'snapshots')
+const SNAPSHOT_FORMAT = 'dsh-market/profile-snapshot'
+const SNAPSHOT_VERSION = 2
+
+/**
+ * Snapshot ids are generated by nextSnapshotId and must never be attacker-
+ * shaped: anything else (paths, '..', absolute paths) is refused BEFORE it
+ * reaches the filesystem, so restoreSnapshot/deleteSnapshot cannot escape the
+ * snapshots directory (issue #98 review B3 — same discipline as backup.ts).
+ */
+const SNAPSHOT_ID_RE = /^snapshot-[0-9A-Za-z-]+$/
+
+function validSnapshotId(id: string): boolean {
+  return SNAPSHOT_ID_RE.test(id)
+}
+
+/** The files a snapshot captures, relative to the profile directory. */
+const SNAPSHOT_FILES = ['package.json', 'cordis.patch.yml', '.dsh-market/state.json'] as const
+
+interface SnapshotFile {
+  path: string
+  /** JSON documents keep their parsed form (re-serialized on restore). */
+  json?: unknown
+  /** Line-oriented text files (cordis.patch.yml) keep their lines. */
+  lines?: string[]
+  /** V2 records absence explicitly so restore can remove a later file. */
+  absent?: true
+}
+
+export interface ProfileSnapshot {
+  /** Present on exact snapshots; omitted by legacy snapshots. */
+  format?: typeof SNAPSHOT_FORMAT
+  /** Version 2 records all tracked paths, including explicit absence. */
+  version?: typeof SNAPSHOT_VERSION
+  /** Snapshot id: the file basename without the .json suffix. */
+  id: string
+  createdAt: number
+  files: SnapshotFile[]
+}
+
+export type SnapshotCaptureResult =
+  | { ok: true; snapshot: ProfileSnapshot }
+  | { ok: false; error: string }
+
+interface NormalizedSnapshot {
+  snapshot: ProfileSnapshot
+  files: SnapshotFile[]
+}
+
+type SnapshotValidation =
+  | { ok: true; value: NormalizedSnapshot }
+  | { ok: false; error: string }
+
+function hasOwn(value: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+/**
+ * Strict shape validation for a parsed snapshot document (issue #98 analysis:
+ * snapshot JSON validation). A snapshot that fails these checks is corrupt —
+ * it can never be restored safely, so listing it would only offer the user a
+ * restore that must fail.
+ */
+function validateSnapshotDocument(value: unknown): SnapshotValidation {
+  if (value === null || typeof value !== 'object') {
+    return { ok: false, error: 'corrupt snapshot document / 快照文档损坏' }
+  }
+  const snap = value as { format?: unknown; version?: unknown; id?: unknown; createdAt?: unknown; files?: unknown }
+  if (typeof snap.id !== 'string' || !validSnapshotId(snap.id)) {
+    return { ok: false, error: 'corrupt snapshot id / 快照 id 损坏' }
+  }
+  if (typeof snap.createdAt !== 'number' || !Number.isFinite(snap.createdAt)) {
+    return { ok: false, error: 'corrupt snapshot timestamp / 快照时间损坏' }
+  }
+  if (!Array.isArray(snap.files)) {
+    return { ok: false, error: 'corrupt snapshot: files is not an array / 快照损坏：files 不是数组' }
+  }
+
+  // Existing unversioned documents are legacy v1. Their omitted optional
+  // paths remain no-ops: older capture also omitted unreadable/invalid files,
+  // so absence cannot be inferred safely after the fact.
+  const legacy = !hasOwn(snap, 'format') && !hasOwn(snap, 'version')
+  if (!legacy && (snap.format !== SNAPSHOT_FORMAT || snap.version !== SNAPSHOT_VERSION)) {
+    return { ok: false, error: 'unsupported snapshot format or version / 不支持的快照格式或版本' }
+  }
+
+  const byPath = new Map<string, SnapshotFile>()
+  for (const file of snap.files) {
+    if (file === null || typeof file !== 'object') {
+      return { ok: false, error: 'corrupt snapshot file entry / 快照文件条目损坏' }
+    }
+    const entry = file as { path?: unknown; json?: unknown; lines?: unknown; absent?: unknown }
+    if (typeof entry.path !== 'string'
+      || !(SNAPSHOT_FILES as readonly string[]).includes(entry.path)
+      || entry.path.includes('..')) {
+      return { ok: false, error: `unsafe snapshot path: ${String(entry.path)} / 快照路径不安全` }
+    }
+    if (byPath.has(entry.path)) {
+      return { ok: false, error: `duplicate snapshot path: ${entry.path} / 快照路径重复` }
+    }
+    const hasJson = hasOwn(entry, 'json')
+    const hasLines = hasOwn(entry, 'lines')
+    const hasAbsent = hasOwn(entry, 'absent')
+    if (Number(hasJson) + Number(hasLines) + Number(hasAbsent) !== 1) {
+      return { ok: false, error: `snapshot file ${entry.path} must have exactly one representation / 快照文件表示无效` }
+    }
+    if (hasLines && (!Array.isArray(entry.lines) || !entry.lines.every(line => typeof line === 'string'))) {
+      return { ok: false, error: `snapshot file ${entry.path} has invalid lines / 快照文件行无效` }
+    }
+    if (hasAbsent && (legacy || entry.absent !== true || entry.path === 'package.json')) {
+      return { ok: false, error: `snapshot file ${entry.path} has invalid absence marker / 快照文件缺失标记无效` }
+    }
+    if ((entry.path === 'package.json' || entry.path === '.dsh-market/state.json') && !hasJson && !hasAbsent) {
+      return { ok: false, error: `snapshot file ${entry.path} has the wrong representation / 快照文件表示类型错误` }
+    }
+    if (entry.path === 'cordis.patch.yml' && !hasLines && !hasAbsent) {
+      return { ok: false, error: `snapshot file ${entry.path} has the wrong representation / 快照文件表示类型错误` }
+    }
+    byPath.set(entry.path, entry as SnapshotFile)
+  }
+
+  if (!legacy && SNAPSHOT_FILES.some(path => !byPath.has(path))) {
+    return { ok: false, error: 'v2 snapshot does not describe every composition file / v2 快照未描述全部组合文件' }
+  }
+  if (!byPath.has('package.json')) {
+    return { ok: false, error: 'snapshot has no package.json / 快照缺少 package.json' }
+  }
+  const files = SNAPSHOT_FILES.flatMap(path => {
+    const file = byPath.get(path)
+    return file === undefined ? [] : [file]
+  })
+  return {
+    ok: true,
+    value: {
+      snapshot: { ...(snap as ProfileSnapshot), files },
+      files,
+    },
+  }
+}
+
+/**
+ * Atomic same-directory replace (write temp + rename): a crash mid-write can
+ * never leave a snapshot file truncated — a half-written snapshot would parse
+ * as corrupt forever and could not be restored.
+ */
+function writeFileAtomic(file: string, content: string): void {
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  try {
+    writeFileSync(temp, content)
+    renameSync(temp, file)
+  } catch (error) {
+    try { rmSync(temp, { force: true }) } catch { /* best-effort temp cleanup */ }
+    throw error
+  }
+}
+
+function isMissingFileError(error: unknown): boolean {
+  return error !== null
+    && typeof error === 'object'
+    && 'code' in error
+    && (error as { code?: unknown }).code === 'ENOENT'
+}
+
+/**
+ * `readFileSync` also reports ENOENT for a dangling symlink. Check the path
+ * entry itself before recording absence so an unreadable composition path can
+ * never be silently converted into a delete instruction for a later restore.
+ */
+function isTrulyAbsent(path: string, readError: unknown): boolean {
+  if (!isMissingFileError(readError)) return false
+  try {
+    lstatSync(path)
+    return false
+  } catch (statError) {
+    return isMissingFileError(statError)
+  }
+}
+
+/** Absolute snapshot directory for a profile. */
+function snapshotDir(profileDir: string): string {
+  return join(profileDir, SNAPSHOT_DIR)
+}
+
+function snapshotFile(profileDir: string, id: string): string {
+  if (!validSnapshotId(id)) throw new Error('invalid snapshot id / 无效的快照 id')
+  return join(snapshotDir(profileDir), `${id}.json`)
+}
+
+/** Basename of the next snapshot (timestamp + sequence for same-ms saves). */
+function nextSnapshotId(profileDir: string): string {
+  const dir = snapshotDir(profileDir)
+  let names: string[] = []
+  try {
+    names = readdirSync(dir)
+  } catch { /* directory absent — no collisions */ }
+  const now = new Date().toISOString().replace(/[:.]/g, '-')
+  let seq = 0
+  let id = `snapshot-${now}`
+  while (names.includes(`${id}.json`)) {
+    seq += 1
+    id = `snapshot-${now}-${String(seq)}`
+  }
+  return id
+}
+
+/** Default number of snapshots retained; configurable via `maxSnapshots`. */
+export const DEFAULT_MAX_SNAPSHOTS = 20
+function captureError(path: string, reason: string, reasonZh: string): string {
+  return `profile composition could not be captured: ${path} ${reason} / 无法捕获 profile 组合：${path} ${reasonZh}`
+}
+
+function errorCode(error: unknown): string | undefined {
+  if (error === null || typeof error !== 'object' || !('code' in error)) return undefined
+  return typeof error.code === 'string' ? error.code : undefined
+}
+
+function captureReadError(path: string, error: unknown): string {
+  const code = errorCode(error)
+  const suffix = code === undefined ? '' : ` (${code})`
+  return captureError(path, `could not be read${suffix}`, `无法读取${suffix}`)
+}
+
+/**
+ * Prune the snapshot directory to the `max` most recent snapshots (newest
+ * first). Extra ones are deleted oldest-first. A non-positive cap is clamped
+ * to 1 — a 0/negative max must never drop the snapshot that was just created
+ * nor invert to keeping the OLDEST set (issue #98 review hardening).
+ * @returns the ids that were deleted.
+ */
+export function pruneSnapshots(profileDir: string, max: number): string[] {
+  return pruneSnapshotsKeeping(profileDir, max)
+}
+
+/** Refuse an existing parent that could redirect a restore outside the profile. */
+function ensureSafeRestoreParent(profileDir: string, parent: string, snapshotPath: string): void {
+  const root = resolve(profileDir)
+  const relativeParent = relative(root, resolve(parent))
+  if (relativeParent === '') return
+  if (isAbsolute(relativeParent) || relativeParent === '..' || relativeParent.startsWith(`..${sep}`)) {
+    throw new Error(`unsafe snapshot restore path: ${snapshotPath} / 快照恢复路径不安全`)
+  }
+  let current = root
+  for (const part of relativeParent.split(sep)) {
+    current = resolve(current, part)
+    let stat
+    try {
+      stat = lstatSync(current)
+    } catch (error) {
+      if (isMissingFileError(error)) return
+      throw error
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`unsafe snapshot restore path: ${snapshotPath} / 快照恢复路径不安全`)
+    }
+  }
+}
+
+interface SnapshotIdOrderKey {
+  category: 0 | 1
+  primary: string
+  sequence: bigint
+  fallback: string
+}
+
+function snapshotIdOrderKey(id: string): SnapshotIdOrderKey {
+  const generated = /^(snapshot-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)(?:-(\d+))?$/
+  const match = generated.exec(id)
+  return match === null
+    ? { category: 1, primary: id, sequence: 0n, fallback: id }
+    : { category: 0, primary: match[1]!, sequence: BigInt(match[2] ?? '0'), fallback: id }
+}
+
+/** @internal Deterministic newest-first order for equal-createdAt documents. */
+export function compareSnapshotIdsNewest(a: string, b: string): number {
+  const aKey = snapshotIdOrderKey(a)
+  const bKey = snapshotIdOrderKey(b)
+  if (aKey.category !== bKey.category) return aKey.category - bKey.category
+  if (aKey.primary !== bKey.primary) return aKey.primary < bKey.primary ? 1 : -1
+  if (aKey.sequence !== bKey.sequence) return aKey.sequence < bKey.sequence ? 1 : -1
+  return aKey.fallback === bKey.fallback ? 0 : aKey.fallback < bKey.fallback ? 1 : -1
+}
+
+function pruneSnapshotsKeeping(profileDir: string, max: number, keepId?: string): string[] {
+  const cap = Math.max(1, max)
+  const all = listSnapshots(profileDir)
+  if (all.length <= cap) return []
+  // Sequence-suffixed ids can share createdAt. Creation must pin its own id
+  // ahead of that tie so it never returns a snapshot pruning just removed.
+  const ordered = keepId === undefined
+    ? all
+    : [...all.filter(snap => snap.id === keepId), ...all.filter(snap => snap.id !== keepId)]
+  const dropped = ordered.slice(cap)
+  for (const snap of dropped) deleteSnapshot(profileDir, snap.id)
+  if (dropped.length > 0) {
+    logEvent('info', 'snapshot', `pruned ${dropped.length} old snapshot(s) (cap ${cap}): ${dropped.map(s => s.id).join(', ')}`)
+  }
+  return dropped.map(s => s.id)
+}
+
+/**
+ * Capture the profile's composition into a version 2 snapshot. Missing
+ * optional files are represented explicitly. An existing optional file that
+ * cannot be read makes capture fail. Invalid market state is represented as
+ * absent because every state reader already observes it as empty and the next
+ * state write replaces it. A missing, unreadable, or invalid package.json is
+ * not snapshot-able. After creating, the directory is pruned to the most
+ * recent `maxSnapshots`.
+ */
+export function createProfileSnapshot(profileDir: string, maxSnapshots: number = DEFAULT_MAX_SNAPSHOTS): SnapshotCaptureResult {
+  const packagePath = join(profileDir, 'package.json')
+  let packageText: string
+  try {
+    packageText = readFileSync(packagePath, 'utf8')
+  } catch (error) {
+    const failure = isTrulyAbsent(packagePath, error)
+      ? captureError('package.json', 'is missing', '缺失')
+      : captureReadError('package.json', error)
+    logEvent('error', 'snapshot', failure)
+    return { ok: false, error: failure }
+  }
+  let packageJson: unknown
+  try {
+    packageJson = JSON.parse(packageText)
+  } catch {
+    const failure = captureError('package.json', 'contains invalid JSON', '包含无效 JSON')
+    logEvent('error', 'snapshot', failure)
+    return { ok: false, error: failure }
+  }
+  const files: SnapshotFile[] = [{ path: 'package.json', json: packageJson }]
+  for (const path of SNAPSHOT_FILES.slice(1)) {
+    const absolutePath = join(profileDir, path)
+    let text: string
+    try {
+      text = readFileSync(absolutePath, 'utf8')
+    } catch (error) {
+      if (isTrulyAbsent(absolutePath, error)) files.push({ path, absent: true })
+      else {
+        const failure = captureReadError(path, error)
+        logEvent('error', 'snapshot', failure)
+        return { ok: false, error: failure }
+      }
+      continue
+    }
+    if (path === '.dsh-market/state.json') {
+      try {
+        files.push({ path, json: JSON.parse(text) })
+      } catch {
+        // readMarketState treats malformed state as empty and every state write
+        // replaces it, so absence is the exact observable composition state.
+        files.push({ path, absent: true })
+        logEvent('warn', 'snapshot', `${path} contains invalid JSON; captured as absent because Market reads it as empty`)
+      }
+    } else {
+      files.push({ path, lines: text.split('\n') })
+    }
+  }
+  const id = nextSnapshotId(profileDir)
+  const snapshot: ProfileSnapshot = {
+    format: SNAPSHOT_FORMAT,
+    version: SNAPSHOT_VERSION,
+    id,
+    createdAt: Date.now(),
+    files,
+  }
+  mkdirSync(snapshotDir(profileDir), { recursive: true, mode: 0o700 })
+  writeFileAtomic(snapshotFile(profileDir, id), `${JSON.stringify(snapshot, null, 2)}\n`)
+  logEvent('info', 'snapshot', `created ${id} (${files.map(file => file.path).join(', ')})`)
+  pruneSnapshotsKeeping(profileDir, maxSnapshots, id)
+  return { ok: true, snapshot }
+}
+
+/**
+ * All snapshots for a profile, newest first. Files that are unparseable,
+ * shape-invalid (bad id/createdAt/files), or whose internal id does not match
+ * the file name are skipped — a snapshot that could never be restored is not
+ * listed (issue #98 analysis: snapshot JSON validation).
+ */
+export function listSnapshots(profileDir: string): ProfileSnapshot[] {
+  let names: string[]
+  try {
+    names = readdirSync(snapshotDir(profileDir)).filter(name => name.endsWith('.json'))
+  } catch {
+    return []
+  }
+  const snapshots: ProfileSnapshot[] = []
+  for (const name of names) {
+    try {
+      const id = name.slice(0, -5)
+      const value = JSON.parse(readFileSync(snapshotFile(profileDir, id), 'utf8')) as unknown
+      const validated = validateSnapshotDocument(value)
+      if (validated.ok && validated.value.snapshot.id === id) snapshots.push(validated.value.snapshot)
+    } catch { /* corrupt snapshot — skip */ }
+  }
+  return snapshots.sort((a, b) => b.createdAt - a.createdAt || compareSnapshotIdsNewest(a.id, b.id))
+}
+
+/**
+ * Restore a snapshot's files into the profile. Version 2 absence markers
+ * remove files created after capture; omitted optional files in unversioned
+ * legacy snapshots remain untouched. Every path is validated before mutation,
+ * each write uses a same-directory temp + rename, and a failure mid-restore
+ * rolls completed writes/deletions back to their pre-restore contents.
+ * @returns the paths restored; an error result when the snapshot is unsafe,
+ * unknown, or a write failed (with any partial writes rolled back).
+ */
+export function restoreSnapshot(profileDir: string, id: string): { ok: boolean; restored: string[]; error?: string } {
+  if (!validSnapshotId(id)) {
+    return { ok: false, restored: [], error: 'invalid snapshot id / 无效的快照 id' }
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(snapshotFile(profileDir, id), 'utf8')) as unknown
+  } catch {
+    return { ok: false, restored: [], error: 'snapshot not found / 快照不存在' }
+  }
+  const validated = validateSnapshotDocument(parsed)
+  if (!validated.ok) return { ok: false, restored: [], error: validated.error }
+  if (validated.value.snapshot.id !== id) {
+    return { ok: false, restored: [], error: 'snapshot id does not match its filename / 快照 id 与文件名不匹配' }
+  }
+  // Materialize every target + its current content FIRST, so a rollback can
+  // restore the pre-restore bytes even if the profile already changed.
+  const writes: Array<{ path: string; target: string; content: string | null; previous: string | null }> = []
+  for (const file of validated.value.files) {
+    const target = join(profileDir, file.path)
+    const content = file.absent === true
+      ? null
+      : file.json !== undefined
+      ? `${JSON.stringify(file.json, null, 2)}\n`
+      : Array.isArray(file.lines) ? `${file.lines.join('\n')}` : ''
+    let previous: string | null = null
+    // Rollback records bytes, not filesystem object identity. Replacing a
+    // symlink or other non-regular target could not be restored faithfully.
+    try {
+      ensureSafeRestoreParent(profileDir, dirname(target), file.path)
+      if (!lstatSync(target).isFile()) {
+        return {
+          ok: false,
+          restored: [],
+          error: `unsafe restore target is not a regular file: ${file.path} / 恢复目标不是常规文件`,
+        }
+      }
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        return { ok: false, restored: [], error: error instanceof Error ? error.message : String(error) }
+      }
+    }
+    try {
+      previous = readFileSync(target, 'utf8')
+    } catch (error) {
+      if (!isMissingFileError(error)) {
+        return { ok: false, restored: [], error: error instanceof Error ? error.message : String(error) }
+      }
+    }
+    writes.push({ path: file.path, target, content, previous })
+  }
+  const completed: typeof writes = []
+  try {
+    for (const write of writes) {
+      if (write.content === null) rmSync(write.target, { force: true })
+      else {
+        mkdirSync(dirname(write.target), { recursive: true })
+        writeFileAtomic(write.target, write.content)
+      }
+      completed.push(write)
+    }
+  } catch (error) {
+    // Roll back completed actions in reverse, including recreating a file that
+    // an explicit absence marker deleted before a later action failed.
+    let rollbackError: unknown = null
+    for (const write of [...completed].reverse()) {
+      try {
+        if (write.previous !== null) {
+          mkdirSync(dirname(write.target), { recursive: true })
+          writeFileAtomic(write.target, write.previous)
+        }
+        else rmSync(write.target, { force: true })
+      } catch (restoreError) {
+        rollbackError ??= restoreError
+      }
+    }
+    const detail = error instanceof Error ? error.message : String(error)
+    const rollbackDetail = rollbackError === null
+      ? ''
+      : `; rollback incomplete: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+    const rollbackStatus = rollbackError === null
+      ? `failed and was rolled back: ${detail}`
+      : `failed; rollback incomplete (${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}); original failure: ${detail}`
+    logEvent('error', 'snapshot', `restore ${id} ${rollbackStatus}`)
+    return { ok: false, restored: [], error: `${detail}${rollbackDetail}` }
+  }
+  const restored = writes.map(write => write.path)
+  logEvent('info', 'snapshot', `restored ${id}: ${restored.join(', ')}`)
+  return { ok: true, restored }
+}
+
+/** Delete one snapshot; true only when it existed and was removed. */
+export function deleteSnapshot(profileDir: string, id: string): boolean {
+  if (!validSnapshotId(id)) return false
+  const file = snapshotFile(profileDir, id)
+  if (!existsSync(file)) return false
+  try {
+    rmSync(file)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/source-migration.ts

@@ -0,0 +1,61 @@
+/**
+ * Safe discovery for legacy Git -> verified npm source migrations (#461).
+ *
+ * This intentionally does less than the normal catalog matcher. A migration
+ * changes package name/publisher and build provenance, so only repository
+ * evidence carried by the installed Git spec may authorize it:
+ *
+ * - bare github:owner/repo matches only the catalog root for that repo;
+ * - #path:/subdir matches only that exact catalog subpath;
+ * - branch/tag/commit/semver selectors are not migrated in v1;
+ * - more than one matching verified npm entry is ambiguous and fails closed.
+ */
+import { NPM_NAME_RE, parseSourceUrl, repoOfTarget } from './sources.ts'
+
+export interface GitToNpmMigration {
+  kind: 'git-to-npm'
+  /** Normalized owner/repo or owner/repo#path:/subdir identity. */
+  repo: string
+  /** Verified npm package declared by the same catalog entry. */
+  target: string
+}
+
+function migratableGitIdentity(spec: string): string | null {
+  if (!spec.startsWith('github:')) return null
+  const hash = spec.indexOf('#')
+  if (hash !== -1) {
+    const selector = spec.slice(hash + 1)
+    // A path selector identifies which package inside a monorepo. Any
+    // other selector expresses an explicit version/ref choice and is
+    // deliberately preserved rather than silently discarded.
+    if (!selector.startsWith('path:/') || selector.includes('&')) return null
+  }
+  return repoOfTarget(spec)
+}
+
+export function findGitToNpmMigration<T extends { url: string; npm?: unknown }>(
+  plugins: readonly T[],
+  spec: string,
+): GitToNpmMigration | null {
+  const identity = migratableGitIdentity(spec)
+  if (identity === null) return null
+  const pathAt = identity.indexOf('#path:/')
+  const wantedRepo = pathAt === -1 ? identity : identity.slice(0, pathAt)
+  const wantedPath = pathAt === -1 ? null : identity.slice(pathAt + '#path:/'.length)
+
+  const candidates = plugins.flatMap((plugin) => {
+    if (typeof plugin.npm !== 'string' || !NPM_NAME_RE.test(plugin.npm)) return []
+    const source = parseSourceUrl(plugin.url)
+    if (source === null || source.repo.toLowerCase() !== wantedRepo) return []
+    if (wantedPath === null) {
+      // A collection root must not guess which /tree/ child was meant.
+      if (source.subpath !== null) return []
+    } else if (source.subpath?.toLowerCase() !== wantedPath) {
+      return []
+    }
+    return [plugin.npm]
+  })
+
+  if (candidates.length !== 1) return null
+  return { kind: 'git-to-npm', repo: identity, target: candidates[0]! }
+}