@vellumai/assistant 0.9.0 → 0.10.0-dev.202606192226.8ed8a6a

package/src/cli/lib/merge-plugin-tree.ts

@@ -0,0 +1,328 @@
+/**
+ * Three-way merge of a plugin tree, used by `plugins upgrade --strategy` to
+ * carry local edits forward across an upgrade instead of discarding them.
+ *
+ * An upgrade has three inputs, exactly like a git merge:
+ * - **base** — the tree the plugin was installed at (the recorded commit,
+ *   re-materialized through the install pipeline; see {@link ./diff-plugin}).
+ * - **ours** — the current on-disk install, carrying any local edits.
+ * - **theirs** — the marketplace's current pin, the tree being upgraded to.
+ *
+ * Per file the merge is delegated to `git merge-file`, the same line-level
+ * three-way algorithm git itself uses: a hunk edited on only one side is taken
+ * from that side, so non-conflicting edits from *both* sides survive. Only a
+ * hunk edited differently on both sides is a true conflict, resolved per the
+ * caller's strategy:
+ * - `ours` keeps the local hunk (`git merge-file --ours`),
+ * - `theirs` keeps the pinned hunk (`git merge-file --theirs`),
+ * - `assistant` writes standard git conflict markers into the file (no resolve
+ *   flag) and reports the path, leaving the conflict for the assistant to
+ *   resolve — exactly the mid-merge working-tree UX.
+ *
+ * File-level add/delete divergence (a file added, removed, or modified on only
+ * one side) is resolved here before any line merge, since `git merge-file`
+ * operates on three existing blobs.
+ *
+ * Binary files cannot be line-merged, so a binary file that diverged on both
+ * sides is resolved whole-file by the strategy (`ours`/`theirs`); under
+ * `assistant` the local copy is kept and the path is reported as a binary
+ * conflict, since markers cannot be written into binary content.
+ *
+ * The `overwrite` strategy never reaches here — it discards local edits and is
+ * a plain re-install at the pin.
+ */
+
+import { execFile } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+import { INSTALL_META_FILENAME } from "./install-from-github.js";
+import { computeFingerprint } from "./plugin-fingerprint.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Cap on a single `git merge-file`; a per-file line merge is near-instant. */
+const MERGE_TIMEOUT_MS = 30_000;
+
+/**
+ * How hunks edited differently on both sides are reconciled. `ours`/`theirs`
+ * auto-resolve toward that side; `assistant` writes conflict markers and
+ * reports the conflict for later resolution. `overwrite` is not a merge
+ * strategy — the caller re-installs the pin wholesale instead of merging.
+ */
+export type PluginMergeStrategy = "ours" | "theirs" | "assistant";
+
+/** Human-readable labels for the conflict markers `assistant` writes. */
+export interface ConflictLabels {
+  readonly ours: string;
+  readonly base: string;
+  readonly theirs: string;
+}
+
+const DEFAULT_CONFLICT_LABELS: ConflictLabels = {
+  ours: "local edits",
+  base: "install baseline",
+  theirs: "upgrade pin",
+};
+
+/** Inputs for a three-way plugin-tree merge. */
+export interface MergePluginTreeOptions {
+  /** Re-materialized install-commit tree (the merge base). */
+  readonly baseDir: string;
+  /** Current on-disk install, carrying local edits (`ours`). */
+  readonly oursDir: string;
+  /** Marketplace-pinned tree being upgraded to (`theirs`). */
+  readonly theirsDir: string;
+  /** Empty directory the merged tree is written into. */
+  readonly destDir: string;
+  /** How to resolve hunks edited differently on both sides. */
+  readonly strategy: PluginMergeStrategy;
+  /** Marker labels for the `assistant` strategy. Defaults are used when omitted. */
+  readonly conflictLabels?: ConflictLabels;
+}
+
+/** Outcome of a three-way plugin-tree merge. */
+export interface PluginMergeResult {
+  /** Number of files written into the destination tree. */
+  readonly fileCount: number;
+  /**
+   * Paths (relative to the tree root) left for the assistant to resolve.
+   * Text files carry git conflict markers; modify/delete divergences keep the
+   * surviving content. Empty for `ours`/`theirs`, which auto-resolve.
+   */
+  readonly conflicts: readonly string[];
+  /**
+   * Paths of binary files that diverged on both sides. The local copy is kept
+   * (markers cannot be written into binary content), so the assistant must
+   * choose a version rather than edit markers. Empty for `ours`/`theirs`.
+   */
+  readonly binaryConflicts: readonly string[];
+}
+
+/** Result of merging a single file. */
+interface MergedFile {
+  readonly content: Buffer;
+  /** Conflict markers were written into `content` (text, `assistant` only). */
+  readonly conflicted: boolean;
+  /** A binary file conflicted; `content` is the kept local copy (`assistant`). */
+  readonly binaryConflicted: boolean;
+}
+
+/** A NUL byte in the leading bytes is the heuristic git uses to flag a blob as binary. */
+function isBinary(buf: Buffer): boolean {
+  const len = Math.min(buf.length, 8000);
+  for (let i = 0; i < len; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/** Write `content` to `destDir/rel`, creating parent directories as needed. */
+function writeInto(destDir: string, rel: string, content: Buffer): void {
+  const abs = join(destDir, rel);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+/**
+ * Line-merge three blobs with `git merge-file`. Non-conflicting hunks from both
+ * sides are always kept. `ours`/`theirs` auto-resolve conflicting hunks toward
+ * that side (no markers); `assistant` writes git conflict markers and flags the
+ * file as conflicted.
+ *
+ * Binary input cannot be line-merged: a side that matches the base did not
+ * change, so the other side's edit is taken. A binary blob changed on *both*
+ * sides is a true conflict — resolved whole-file by `ours`/`theirs`, or kept as
+ * the local copy and flagged under `assistant` (no markers possible).
+ */
+async function threeWayMergeFile(
+  ours: Buffer,
+  base: Buffer,
+  theirs: Buffer,
+  strategy: PluginMergeStrategy,
+  labels: ConflictLabels,
+): Promise<MergedFile> {
+  if (isBinary(ours) || isBinary(base) || isBinary(theirs)) {
+    if (ours.equals(base))
+      return { content: theirs, conflicted: false, binaryConflicted: false };
+    if (theirs.equals(base))
+      return { content: ours, conflicted: false, binaryConflicted: false };
+    if (strategy === "assistant") {
+      return { content: ours, conflicted: false, binaryConflicted: true };
+    }
+    return {
+      content: strategy === "ours" ? ours : theirs,
+      conflicted: false,
+      binaryConflicted: false,
+    };
+  }
+
+  const scratch = mkdtempSync(join(tmpdir(), "plugin-merge-file-"));
+  try {
+    const oursPath = join(scratch, "ours");
+    const basePath = join(scratch, "base");
+    const theirsPath = join(scratch, "theirs");
+    writeFileSync(oursPath, ours);
+    writeFileSync(basePath, base);
+    writeFileSync(theirsPath, theirs);
+
+    // `-p` prints the merged result to stdout instead of editing `ours` in
+    // place. `--ours`/`--theirs` auto-resolve conflicting hunks toward that
+    // side; with neither (the `assistant` strategy) git writes conflict
+    // markers, labelled via `-L` so the assistant can tell the sides apart.
+    const args = ["merge-file", "-p"];
+    if (strategy === "ours" || strategy === "theirs") {
+      args.push(`--${strategy}`);
+    } else {
+      args.push("-L", labels.ours, "-L", labels.base, "-L", labels.theirs);
+    }
+    args.push(oursPath, basePath, theirsPath);
+    try {
+      const { stdout } = await execFileAsync("git", args, {
+        cwd: scratch,
+        encoding: "buffer",
+        timeout: MERGE_TIMEOUT_MS,
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      return { content: stdout, conflicted: false, binaryConflicted: false };
+    } catch (err) {
+      // `git merge-file` exits with the (positive) conflict count when markers
+      // were left, still printing the full merged bytes to stdout — that is the
+      // only rejection we may install. A killed process (timeout) or a
+      // `maxBuffer` overflow also rejects here, but with truncated/partial
+      // stdout we must NOT install it, or a large conflicted file would be
+      // silently corrupted; surface those as errors. A resolving flag never
+      // leaves conflicts, so any non-zero exit there is likewise a real
+      // failure.
+      const e = err as {
+        stdout?: Buffer;
+        code?: unknown;
+        killed?: boolean;
+        signal?: string | null;
+      };
+      const isConflictExit =
+        strategy === "assistant" &&
+        e.killed !== true &&
+        e.signal == null &&
+        typeof e.code === "number" &&
+        e.code > 0;
+      if (isConflictExit && Buffer.isBuffer(e.stdout)) {
+        return { content: e.stdout, conflicted: true, binaryConflicted: false };
+      }
+      throw err;
+    }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Three-way merge `oursDir`/`theirsDir` against `baseDir` into `destDir` per
+ * `strategy`. The provenance sidecar is excluded on every side — it is
+ * rewritten by the caller after the swap and must not be carried through the
+ * merge.
+ *
+ * Returns the file count plus, for the `assistant` strategy, the paths left for
+ * the assistant to resolve (text files with conflict markers and modify/delete
+ * divergences) and the binary files that conflicted.
+ */
+export async function mergePluginTree({
+  baseDir,
+  oursDir,
+  theirsDir,
+  destDir,
+  strategy,
+  conflictLabels,
+}: MergePluginTreeOptions): Promise<PluginMergeResult> {
+  const labels = conflictLabels ?? DEFAULT_CONFLICT_LABELS;
+  const exclude = [INSTALL_META_FILENAME];
+  const base = computeFingerprint(baseDir, exclude).files;
+  const ours = computeFingerprint(oursDir, exclude).files;
+  const theirs = computeFingerprint(theirsDir, exclude).files;
+
+  const paths = new Set([
+    ...Object.keys(base),
+    ...Object.keys(ours),
+    ...Object.keys(theirs),
+  ]);
+
+  const readBase = (rel: string) => readFileSync(join(baseDir, rel));
+  const readOurs = (rel: string) => readFileSync(join(oursDir, rel));
+  const readTheirs = (rel: string) => readFileSync(join(theirsDir, rel));
+
+  let fileCount = 0;
+  const conflicts: string[] = [];
+  const binaryConflicts: string[] = [];
+  const keep = (rel: string, content: Buffer): void => {
+    writeInto(destDir, rel, content);
+    fileCount++;
+  };
+
+  for (const rel of paths) {
+    const b = base[rel];
+    const o = ours[rel];
+    const t = theirs[rel];
+
+    if (o !== undefined && t !== undefined) {
+      // Present on both sides: identical needs no merge; otherwise line-merge
+      // (an empty base when the file was added on both sides).
+      if (o === t) {
+        keep(rel, readOurs(rel));
+      } else {
+        const merged = await threeWayMergeFile(
+          readOurs(rel),
+          b !== undefined ? readBase(rel) : Buffer.alloc(0),
+          readTheirs(rel),
+          strategy,
+          labels,
+        );
+        keep(rel, merged.content);
+        if (merged.conflicted) conflicts.push(rel);
+        if (merged.binaryConflicted) binaryConflicts.push(rel);
+      }
+      continue;
+    }
+
+    if (o !== undefined) {
+      // Present only locally. A local-only addition (no base) always survives.
+      // A file deleted upstream is a delete: drop it when unchanged locally.
+      // On a modify/delete conflict `ours` keeps the edit and `theirs` honors
+      // the deletion; `assistant` keeps the edit and flags it (a whole-file
+      // conflict markers can't express).
+      if (b === undefined || (b !== o && strategy !== "theirs")) {
+        keep(rel, readOurs(rel));
+        if (b !== undefined && b !== o && strategy === "assistant") {
+          conflicts.push(rel);
+        }
+      }
+      continue;
+    }
+
+    if (t !== undefined) {
+      // Present only at the pin. A remote-only addition (no base) always lands.
+      // A file deleted locally is a delete: keep upstream's removal when the
+      // pin left it unchanged. On a delete/modify conflict `theirs` keeps the
+      // pin's edit and `ours` honors the local deletion; `assistant` keeps the
+      // pin's edit and flags it.
+      if (b === undefined || (b !== t && strategy !== "ours")) {
+        keep(rel, readTheirs(rel));
+        if (b !== undefined && b !== t && strategy === "assistant") {
+          conflicts.push(rel);
+        }
+      }
+      continue;
+    }
+
+    // Present only in the base: removed on both sides, so it stays removed.
+  }
+
+  return { fileCount, conflicts, binaryConflicts };
+}

package/src/cli/lib/plugin-fingerprint.ts

@@ -120,6 +120,20 @@ export function compareFingerprint(
   };
 }
 
+/**
+ * Whether two fingerprints cover the same files with identical digests. Used to
+ * confirm a re-materialized tree faithfully reproduces a recorded baseline
+ * before it is trusted as a merge base.
+ */
+export function fingerprintsEqual(a: Fingerprint, b: Fingerprint): boolean {
+  const aKeys = Object.keys(a.files);
+  if (aKeys.length !== Object.keys(b.files).length) return false;
+  for (const key of aKeys) {
+    if (a.files[key] !== b.files[key]) return false;
+  }
+  return true;
+}
+
 /**
  * Parse a fingerprint from already-decoded JSON. Lenient by design — any shape
  * problem yields `null` so an older or hand-edited sidecar simply reports "no

package/src/cli/lib/plugin-marketplace.ts

@@ -35,6 +35,17 @@ const MARKETPLACE_SOURCE_OWNER = "vellum-ai";
 const MARKETPLACE_SOURCE_REPO = "vellum-assistant";
 const MARKETPLACE_FILE_PATH = "plugins/marketplace.json";
 
+/**
+ * Canonical GitHub coordinates of the marketplace manifest, exported so
+ * sibling readers (e.g. {@link ./plugin-pin-history}) resolve the same
+ * `owner/repo:path` rather than re-declaring it.
+ */
+export const MARKETPLACE_MANIFEST_LOCATION = {
+  owner: MARKETPLACE_SOURCE_OWNER,
+  repo: MARKETPLACE_SOURCE_REPO,
+  path: MARKETPLACE_FILE_PATH,
+} as const;
+
 // ---------------------------------------------------------------------------
 // Manifest schema (subset of the Claude Code marketplace schema)
 // ---------------------------------------------------------------------------

package/src/cli/lib/plugin-pin-history.ts

@@ -0,0 +1,257 @@
+/**
+ * Reconstruct the history of marketplace pins for a single plugin.
+ *
+ * The curated `plugins/marketplace.json` manifest (see {@link ./plugin-marketplace})
+ * records only the *current* pin for each plugin — there is no stored version
+ * list. But the manifest is a file in a Git repo, and every time a curator bumps
+ * a plugin's pin, that is a commit to the manifest. So the history of reviewed
+ * pins already exists as the commit history of that one file: this module walks
+ * it (newest → oldest) via the GitHub API and reports the distinct pins a plugin
+ * has been promoted to over time, each tagged with the marketplace commit an
+ * install can reproduce it from.
+ *
+ * Why this is the safe source for "install an older version": every commit on
+ * the default branch was reviewed and merged, so a pin drawn from this history
+ * is a reviewed, known-good revision — unlike an arbitrary caller-supplied ref,
+ * which the install route deliberately refuses. Resolving an older pin to the
+ * marketplace commit that introduced it (rather than the plugin SHA directly)
+ * also means the install reads that era's manifest, so the curated adapter stub
+ * matches the pin and the historical version reproduces coherently.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring the
+ * sibling plugin libraries.
+ */
+
+import { type FetchLike, sanitizePluginName } from "./install-from-github.js";
+import {
+  fetchMarketplaceEntries,
+  MARKETPLACE_MANIFEST_LOCATION,
+} from "./plugin-marketplace.js";
+
+/** Default number of distinct historical pins surfaced by `plugins versions`. */
+export const DEFAULT_PIN_HISTORY_LIMIT = 5;
+
+/**
+ * Cap on how many manifest-touching commits are inspected in one walk. Bounds
+ * the GitHub API cost: a plugin whose pin changes rarely could otherwise force
+ * a fetch of the manifest at every commit that touched it for *any* plugin.
+ * Well above {@link DEFAULT_PIN_HISTORY_LIMIT} so the default listing is
+ * complete in all but pathological histories.
+ */
+const MAX_MARKETPLACE_COMMITS_SCANNED = 100;
+
+/** A single point in a plugin's marketplace-pin history. */
+export interface PluginPinHistoryEntry {
+  /** Plugin commit SHA pinned at this point in history. */
+  readonly pin: string;
+  /**
+   * Marketplace-manifest commit to install this pin from — the newest commit
+   * that carries it. Installing with this as the marketplace ref reproduces the
+   * pin together with the curated adapter stub of the same era.
+   */
+  readonly marketplaceCommit: string;
+  /**
+   * ISO-8601 committer date (UTC) of {@link PluginPinHistoryEntry.marketplaceCommit},
+   * i.e. when this pin was promoted; `null` when the date could not be read.
+   */
+  readonly promotedAt: string | null;
+  /** True for the pin currently active on the default branch. */
+  readonly current: boolean;
+}
+
+/** Options controlling the pin-history walk. */
+export interface ListPinHistoryOptions {
+  /** Max distinct pins to return (newest first). Defaults to {@link DEFAULT_PIN_HISTORY_LIMIT}. */
+  readonly limit?: number;
+  /** Marketplace branch to read history from. Defaults to `main`. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface ListPinHistoryDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/** Shape of a commit entry from the GitHub commits API. */
+interface GitHubCommitListEntry {
+  readonly sha: string;
+  readonly commit: {
+    readonly committer?: { readonly date?: string } | null;
+  } | null;
+}
+
+/** A manifest-touching commit and its committer date. */
+interface ManifestCommit {
+  readonly sha: string;
+  readonly date: string | null;
+}
+
+/** The pin-history walk could not read the marketplace commit list. */
+export class PluginPinHistoryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PluginPinHistoryError";
+  }
+}
+
+/**
+ * List the commits that touched the marketplace manifest on `ref`, newest
+ * first, capped at {@link MAX_MARKETPLACE_COMMITS_SCANNED}. A 404 (the file
+ * never existed at this ref) yields an empty list.
+ */
+async function listManifestCommits(
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<ManifestCommit[]> {
+  const { owner, repo, path } = MARKETPLACE_MANIFEST_LOCATION;
+  const url =
+    `https://api.github.com/repos/${owner}/${repo}/commits` +
+    `?path=${encodeURIComponent(path)}` +
+    `&sha=${encodeURIComponent(ref)}` +
+    `&per_page=${MAX_MARKETPLACE_COMMITS_SCANNED}`;
+
+  const res = await fetchFn(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new PluginPinHistoryError(
+      `Marketplace commit history fetch failed for ${path} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  let body: unknown;
+  try {
+    body = JSON.parse(await res.text());
+  } catch (err) {
+    throw new PluginPinHistoryError(
+      `Marketplace commit history is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (!Array.isArray(body)) {
+    throw new PluginPinHistoryError(
+      "Marketplace commit history response was not an array",
+    );
+  }
+
+  const commits: ManifestCommit[] = [];
+  for (const item of body as GitHubCommitListEntry[]) {
+    if (typeof item?.sha !== "string") continue;
+    const rawDate = item.commit?.committer?.date;
+    commits.push({
+      sha: item.sha,
+      date: typeof rawDate === "string" ? rawDate : null,
+    });
+  }
+  return commits;
+}
+
+/**
+ * Resolve the plugin's pinned SHA in the manifest at a specific marketplace
+ * commit, or `null` when no entry claims the name at that revision.
+ */
+async function pinAtCommit(
+  name: string,
+  marketplaceCommit: string,
+  fetchFn: FetchLike,
+): Promise<string | null> {
+  const entries = await fetchMarketplaceEntries(
+    { fetch: fetchFn },
+    { ref: marketplaceCommit },
+  );
+  return entries.find((e) => e.name === name)?.source.ref ?? null;
+}
+
+/**
+ * Walk a plugin's distinct marketplace pins, newest first. Each pin is yielded
+ * once, tagged with the newest marketplace commit carrying it. Revisions where
+ * the plugin is absent from the manifest are skipped (a gap, not a pin). The
+ * `current` flag is set against the pin live on `ref` today.
+ *
+ * Bounded by {@link MAX_MARKETPLACE_COMMITS_SCANNED} commits scanned.
+ */
+async function* iteratePinHistory(
+  name: string,
+  ref: string,
+  fetchFn: FetchLike,
+): AsyncGenerator<PluginPinHistoryEntry> {
+  const commits = await listManifestCommits(ref, fetchFn);
+  if (commits.length === 0) return;
+
+  // The pin live on the branch today, used to flag the current entry. Reading
+  // it explicitly (rather than assuming the newest commit carries it) stays
+  // correct even if the plugin was just removed from the manifest at the tip.
+  const currentPin = await pinAtCommit(name, ref, fetchFn);
+
+  let lastPin: string | null = null;
+  for (const commit of commits) {
+    const pin = await pinAtCommit(name, commit.sha, fetchFn);
+    if (pin === null) continue;
+    if (pin === lastPin) continue;
+    lastPin = pin;
+    yield {
+      pin,
+      marketplaceCommit: commit.sha,
+      promotedAt: commit.date,
+      current: currentPin !== null && pin === currentPin,
+    };
+  }
+}
+
+/**
+ * List a plugin's distinct marketplace pins, newest first, capped at
+ * `limit` (default {@link DEFAULT_PIN_HISTORY_LIMIT}). The first entry is the
+ * current pin. An empty list means the plugin has no resolvable history at this
+ * ref (never in the manifest, or the manifest does not exist).
+ *
+ * Throws {@link PluginPinHistoryError} when the commit list cannot be read, and
+ * propagates a `MarketplaceFetchError` if a manifest revision fails to parse.
+ */
+export async function listPinHistory(
+  name: string,
+  deps: ListPinHistoryDeps,
+  opts: ListPinHistoryOptions = {},
+): Promise<PluginPinHistoryEntry[]> {
+  const sanitized = sanitizePluginName(name);
+  const ref = opts.ref ?? "main";
+  const limit = opts.limit ?? DEFAULT_PIN_HISTORY_LIMIT;
+
+  const out: PluginPinHistoryEntry[] = [];
+  for await (const entry of iteratePinHistory(sanitized, ref, deps.fetch)) {
+    out.push(entry);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Resolve a plugin pin (a full commit SHA) to the marketplace commit it should
+ * be installed from, by searching the plugin's pin history. Returns `null` when
+ * the pin is not found in the scanned history — i.e. it is not a reviewed pin
+ * this plugin was ever promoted to (or it predates the scan window).
+ *
+ * Case-insensitive on the SHA, matching the rest of the install pipeline. The
+ * search walks the full scan window, not just the `limit` shown by
+ * {@link listPinHistory}, so a pin older than the default listing still
+ * resolves.
+ */
+export async function resolvePinToMarketplaceCommit(
+  name: string,
+  pin: string,
+  deps: ListPinHistoryDeps,
+  opts: { readonly ref?: string } = {},
+): Promise<PluginPinHistoryEntry | null> {
+  const sanitized = sanitizePluginName(name);
+  const ref = opts.ref ?? "main";
+  const target = pin.trim().toLowerCase();
+  if (target.length === 0) return null;
+
+  for await (const entry of iteratePinHistory(sanitized, ref, deps.fetch)) {
+    if (entry.pin.toLowerCase() === target) return entry;
+  }
+  return null;
+}