@vellumai/assistant 0.9.0 → 0.9.1-staging.1

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

@@ -0,0 +1,313 @@
+/**
+ * Tests for {@link mergePluginTree}.
+ *
+ * The merge is exercised against three real temp directories (base/ours/theirs)
+ * and the merged tree is read back from a fourth (dest). `git merge-file` runs
+ * for real — these tests assert the line-level merge behavior (non-conflicting
+ * hunks from both sides survive; conflicts resolve toward the strategy), the
+ * file-level add/delete resolution, and binary whole-file handling.
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { mergePluginTree } from "../merge-plugin-tree.js";
+
+/** A file tree keyed by POSIX-relative path; Buffer values are binary files. */
+type Tree = Record<string, string | Buffer>;
+
+let scratch: string;
+let baseDir: string;
+let oursDir: string;
+let theirsDir: string;
+let destDir: string;
+
+function writeTree(root: string, tree: Tree): void {
+  for (const [rel, content] of Object.entries(tree)) {
+    const abs = join(root, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  }
+}
+
+/** Read a merged file as UTF-8, or null when absent from the dest tree. */
+function read(rel: string): string | null {
+  const abs = join(destDir, rel);
+  try {
+    return readFileSync(abs, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+beforeEach(() => {
+  scratch = mkdtempSync(join(tmpdir(), "merge-plugin-tree-"));
+  baseDir = join(scratch, "base");
+  oursDir = join(scratch, "ours");
+  theirsDir = join(scratch, "theirs");
+  destDir = join(scratch, "dest");
+  for (const d of [baseDir, oursDir, theirsDir, destDir]) {
+    mkdirSync(d, { recursive: true });
+  }
+});
+
+afterEach(() => {
+  rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("mergePluginTree", () => {
+  test("keeps non-conflicting edits from both sides and resolves conflicts toward ours", async () => {
+    // GIVEN a file edited on disjoint lines by each side, a true conflict, and
+    // a one-sided addition on each side
+    writeTree(baseDir, {
+      "common.txt": "a\nb\nc\n",
+      "conflict.txt": "base\n",
+    });
+    writeTree(oursDir, {
+      "common.txt": "A\nb\nc\n",
+      "conflict.txt": "ours\n",
+      "local-only.txt": "local\n",
+    });
+    writeTree(theirsDir, {
+      "common.txt": "a\nb\nC\n",
+      "conflict.txt": "theirs\n",
+      "remote-only.txt": "remote\n",
+    });
+
+    // WHEN merged with the `ours` strategy
+    const count = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "ours",
+    });
+
+    // THEN both disjoint edits survive, both additions land, and the conflict
+    // resolves toward the local edit
+    expect(read("common.txt")).toBe("A\nb\nC\n");
+    expect(read("local-only.txt")).toBe("local\n");
+    expect(read("remote-only.txt")).toBe("remote\n");
+    expect(read("conflict.txt")).toBe("ours\n");
+    expect(count).toBe(4);
+  });
+
+  test("resolves conflicts toward the pin under the theirs strategy", async () => {
+    // GIVEN a file edited differently on both sides
+    writeTree(baseDir, { "conflict.txt": "base\n" });
+    writeTree(oursDir, { "conflict.txt": "ours\n" });
+    writeTree(theirsDir, { "conflict.txt": "theirs\n" });
+
+    // WHEN merged with the `theirs` strategy
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN the conflicting hunk resolves toward the pin
+    expect(read("conflict.txt")).toBe("theirs\n");
+  });
+
+  test("never writes conflict markers", async () => {
+    // GIVEN a hard conflict on every line
+    writeTree(baseDir, { "f.txt": "1\n2\n3\n" });
+    writeTree(oursDir, { "f.txt": "1\nOURS\n3\n" });
+    writeTree(theirsDir, { "f.txt": "1\nTHEIRS\n3\n" });
+
+    // WHEN merged
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "ours",
+    });
+
+    // THEN the result carries no git conflict markers
+    const merged = read("f.txt") ?? "";
+    expect(merged).not.toContain("<<<<<<<");
+    expect(merged).not.toContain("=======");
+    expect(merged).not.toContain(">>>>>>>");
+  });
+
+  test("drops a file deleted upstream when it is unchanged locally", async () => {
+    // GIVEN a file present at base and locally but removed at the pin
+    writeTree(baseDir, { "gone.txt": "keep\n", "stay.txt": "x\n" });
+    writeTree(oursDir, { "gone.txt": "keep\n", "stay.txt": "x\n" });
+    writeTree(theirsDir, { "stay.txt": "x\n" });
+
+    // WHEN merged
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN the upstream deletion is honored
+    expect(read("gone.txt")).toBeNull();
+    expect(read("stay.txt")).toBe("x\n");
+  });
+
+  test("keeps a locally-edited file the pin deleted under the ours strategy", async () => {
+    // GIVEN a modify/delete conflict: edited locally, deleted at the pin
+    writeTree(baseDir, { "f.txt": "base\n" });
+    writeTree(oursDir, { "f.txt": "local edit\n" });
+    writeTree(theirsDir, {});
+
+    // WHEN merged with `ours`
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "ours",
+    });
+
+    // THEN the local edit wins over the deletion
+    expect(read("f.txt")).toBe("local edit\n");
+  });
+
+  test("honors the pin's deletion of a locally-edited file under the theirs strategy", async () => {
+    // GIVEN the same modify/delete conflict
+    writeTree(baseDir, { "f.txt": "base\n" });
+    writeTree(oursDir, { "f.txt": "local edit\n" });
+    writeTree(theirsDir, {});
+
+    // WHEN merged with `theirs`
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN the deletion wins over the local edit
+    expect(read("f.txt")).toBeNull();
+  });
+
+  test("resolves a binary conflict whole-file by strategy rather than line-merging", async () => {
+    // GIVEN a binary file (NUL bytes) diverged on both sides
+    const base = Buffer.from([0x00, 0x01, 0x02]);
+    const ours = Buffer.from([0x00, 0xaa, 0xbb]);
+    const theirs = Buffer.from([0x00, 0xcc, 0xdd]);
+    writeTree(baseDir, { "img.bin": base });
+    writeTree(oursDir, { "img.bin": ours });
+    writeTree(theirsDir, { "img.bin": theirs });
+
+    // WHEN merged with `theirs`
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN the whole pin blob is taken, byte-for-byte (no markers, no corruption)
+    expect(readFileSync(join(destDir, "img.bin")).equals(theirs)).toBe(true);
+  });
+
+  test("keeps a one-sided binary change rather than resolving by strategy", async () => {
+    // GIVEN a binary file the pin updated but the local install left untouched
+    const base = Buffer.from([0x00, 0x01, 0x02]);
+    const theirs = Buffer.from([0x00, 0xcc, 0xdd]);
+    writeTree(baseDir, { "img.bin": base });
+    writeTree(oursDir, { "img.bin": base });
+    writeTree(theirsDir, { "img.bin": theirs });
+
+    // WHEN merged with `ours` (which only governs true conflicts)
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "ours",
+    });
+
+    // THEN the upstream-only update survives instead of being dropped
+    expect(readFileSync(join(destDir, "img.bin")).equals(theirs)).toBe(true);
+  });
+
+  test("keeps a one-sided local binary edit under the theirs strategy", async () => {
+    // GIVEN a binary file edited locally but unchanged in the pin
+    const base = Buffer.from([0x00, 0x01, 0x02]);
+    const ours = Buffer.from([0x00, 0xaa, 0xbb]);
+    writeTree(baseDir, { "img.bin": base });
+    writeTree(oursDir, { "img.bin": ours });
+    writeTree(theirsDir, { "img.bin": base });
+
+    // WHEN merged with `theirs` (which only governs true conflicts)
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "theirs",
+    });
+
+    // THEN the local-only edit survives instead of being reverted to the pin
+    expect(readFileSync(join(destDir, "img.bin")).equals(ours)).toBe(true);
+  });
+
+  test("excludes the provenance sidecar from the merge", async () => {
+    // GIVEN an install-meta sidecar present on every side with differing content
+    writeTree(baseDir, {
+      "install-meta.json": '{"commit":"base"}',
+      "f.txt": "x\n",
+    });
+    writeTree(oursDir, {
+      "install-meta.json": '{"commit":"ours"}',
+      "f.txt": "x\n",
+    });
+    writeTree(theirsDir, {
+      "install-meta.json": '{"commit":"theirs"}',
+      "f.txt": "x\n",
+    });
+
+    // WHEN merged
+    const count = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "ours",
+    });
+
+    // THEN the sidecar is never carried through (the caller rewrites it)
+    expect(read("install-meta.json")).toBeNull();
+    expect(count).toBe(1);
+  });
+
+  test("merges files in nested directories", async () => {
+    // GIVEN a conflict on a deeply-nested file
+    writeTree(baseDir, { "src/a/b.txt": "base\n" });
+    writeTree(oursDir, { "src/a/b.txt": "ours\n" });
+    writeTree(theirsDir, { "src/a/b.txt": "theirs\n" });
+
+    // WHEN merged
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "ours",
+    });
+
+    // THEN the nested path is preserved and resolved
+    expect(read("src/a/b.txt")).toBe("ours\n");
+  });
+});

package/src/cli/lib/__tests__/upgrade-plugin.test.ts

@@ -18,7 +18,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import {
@@ -26,8 +26,14 @@ import {
   type GitRunner,
   PluginSourceUnavailableError,
 } from "../install-from-github.js";
+import { computeFingerprint } from "../plugin-fingerprint.js";
 import { PluginNotInstalledError } from "../uninstall-plugin.js";
-import { PluginNotUpgradableError, upgradePlugin } from "../upgrade-plugin.js";
+import {
+  PluginMergeBaselineError,
+  PluginNotUpgradableError,
+  PluginUpgradeStrategyUnsupportedError,
+  upgradePlugin,
+} from "../upgrade-plugin.js";
 
 const SHA_A = "a".repeat(40);
 const SHA_B = "b".repeat(40);
@@ -382,3 +388,248 @@ describe("upgradePlugin", () => {
     expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
   });
 });
+
+/** A file tree keyed by POSIX-relative path. */
+type Tree = Record<string, string>;
+
+/**
+ * A fake clone whose materialized tree depends on the fetched ref, so a merge
+ * upgrade's base clone (`source.ref` = the recorded install commit) and pin
+ * clone (`source.ref` = the marketplace pin) yield different trees. The ref is
+ * the last `git fetch` argument; `rev-parse HEAD` echoes it back so the
+ * checked-out commit matches the requested ref.
+ */
+function treeGitRunner(treesByRef: Record<string, Tree>): GitRunner {
+  const refByCwd = new Map<string, string>();
+  return async (args, { cwd }) => {
+    switch (args[0]) {
+      case "fetch": {
+        const ref = args[args.length - 1];
+        refByCwd.set(cwd, ref);
+        const tree = treesByRef[ref] ?? {};
+        for (const [rel, content] of Object.entries(tree)) {
+          const abs = join(cwd, rel);
+          mkdirSync(dirname(abs), { recursive: true });
+          writeFileSync(abs, content);
+        }
+        // `.git` is stripped during materialization; create it so the strip
+        // path is exercised, matching a real clone.
+        mkdirSync(join(cwd, ".git"), { recursive: true });
+        writeFileSync(join(cwd, ".git", "config"), "[core]\n");
+        return { stdout: "" };
+      }
+      case "rev-parse":
+        return { stdout: `${refByCwd.get(cwd) ?? ""}\n` };
+      default:
+        return { stdout: "" };
+    }
+  };
+}
+
+/**
+ * Materialize an installed copy of `ours` on disk plus a provenance sidecar
+ * recording `commit` and a fingerprint. By default the fingerprint is computed
+ * over `base` (what install materialized); pass `fingerprintTree` to record a
+ * mismatching baseline.
+ */
+function installMergeCopy(
+  name: string,
+  ours: Tree,
+  commit: string,
+  fingerprintTree: Tree | null,
+): void {
+  const dir = join(pluginsDir, name);
+  mkdirSync(dir, { recursive: true });
+  for (const [rel, content] of Object.entries(ours)) {
+    const abs = join(dir, rel);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  }
+  const sidecar: Record<string, unknown> = {
+    origin: "vellum",
+    name,
+    source: { kind: "github", owner: "example-org", repo: name, ref: commit },
+    commit,
+    installedAt: "2026-06-10T12:00:00.000Z",
+  };
+  if (fingerprintTree !== null) {
+    const refDir = mkdtempSync(join(tmpdir(), "merge-fingerprint-"));
+    try {
+      for (const [rel, content] of Object.entries(fingerprintTree)) {
+        const abs = join(refDir, rel);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+      }
+      sidecar.fingerprint = computeFingerprint(refDir, ["install-meta.json"]);
+    } finally {
+      rmSync(refDir, { recursive: true, force: true });
+    }
+  }
+  writeFileSync(join(dir, "install-meta.json"), JSON.stringify(sidecar));
+}
+
+/** Read an installed file's contents, or null when absent. */
+function installedFile(name: string, rel: string): string | null {
+  const path = join(pluginsDir, name, rel);
+  return existsSync(path) ? readFileSync(path, "utf-8") : null;
+}
+
+describe("upgradePlugin --strategy", () => {
+  // base → ours / theirs trees shared by the three-way merge tests:
+  // - common.txt: edited on disjoint lines by each side (a clean auto-merge)
+  // - conflict.txt: edited differently on both sides (a true conflict)
+  // - local-only.txt / remote-only.txt: added on one side only
+  const BASE: Tree = {
+    "common.txt": "a\nb\nc\n",
+    "conflict.txt": "base\n",
+  };
+  const OURS: Tree = {
+    "common.txt": "A\nb\nc\n",
+    "conflict.txt": "ours\n",
+    "local-only.txt": "added locally\n",
+  };
+  const THEIRS: Tree = {
+    "common.txt": "a\nb\nC\n",
+    "conflict.txt": "theirs\n",
+    "remote-only.txt": "added upstream\n",
+  };
+
+  test("--strategy ours carries both sides' edits and resolves conflicts toward local", async () => {
+    // GIVEN an install at SHA_A with local edits, and a pin at SHA_B
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
+
+    // WHEN the plugin is upgraded with the `ours` strategy
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "ours" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it moves to the pin and records the strategy
+    expect(result.outcome).toBe("upgraded");
+    expect(result.toCommit).toBe(SHA_B);
+    expect(result.strategy).toBe("ours");
+    // AND non-conflicting edits from both sides survive
+    expect(installedFile("level-up", "common.txt")).toBe("A\nb\nC\n");
+    expect(installedFile("level-up", "local-only.txt")).toBe("added locally\n");
+    expect(installedFile("level-up", "remote-only.txt")).toBe(
+      "added upstream\n",
+    );
+    // AND the conflicting file resolves toward the local edit
+    expect(installedFile("level-up", "conflict.txt")).toBe("ours\n");
+  });
+
+  test("--strategy theirs carries both sides' edits and resolves conflicts toward the pin", async () => {
+    // GIVEN an install at SHA_A with local edits, and a pin at SHA_B
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
+
+    // WHEN the plugin is upgraded with the `theirs` strategy
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "theirs" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN non-conflicting edits from both sides still survive
+    expect(result.strategy).toBe("theirs");
+    expect(installedFile("level-up", "common.txt")).toBe("A\nb\nC\n");
+    expect(installedFile("level-up", "local-only.txt")).toBe("added locally\n");
+    expect(installedFile("level-up", "remote-only.txt")).toBe(
+      "added upstream\n",
+    );
+    // AND the conflicting file resolves toward the pin
+    expect(installedFile("level-up", "conflict.txt")).toBe("theirs\n");
+  });
+
+  test("--strategy overwrite discards local edits and re-installs the pin wholesale", async () => {
+    // GIVEN an install at SHA_A with a local-only file, and a pin at SHA_B
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
+
+    // WHEN the plugin is upgraded with the `overwrite` strategy
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "overwrite" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the on-disk tree is exactly the pin — local edits are gone
+    expect(result.strategy).toBe("overwrite");
+    expect(installedFile("level-up", "common.txt")).toBe("a\nb\nC\n");
+    expect(installedFile("level-up", "conflict.txt")).toBe("theirs\n");
+    expect(installedFile("level-up", "remote-only.txt")).toBe(
+      "added upstream\n",
+    );
+    expect(installedFile("level-up", "local-only.txt")).toBeNull();
+  });
+
+  test("defaults to overwrite when no strategy is given", async () => {
+    // GIVEN an install with a local-only file and an advanced pin
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
+
+    // WHEN the plugin is upgraded without a strategy
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it overwrites: the local-only file is dropped
+    expect(result.strategy).toBe("overwrite");
+    expect(installedFile("level-up", "local-only.txt")).toBeNull();
+  });
+
+  test("throws PluginUpgradeStrategyUnsupportedError for the assistant strategy", async () => {
+    // GIVEN an installed copy and an advanced pin
+    installMergeCopy("level-up", OURS, SHA_A, BASE);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+
+    // WHEN an upgrade requests the not-yet-implemented `assistant` strategy
+    // THEN it is rejected before any clone runs
+    await expect(
+      upgradePlugin(
+        { name: "level-up", strategy: "assistant" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginUpgradeStrategyUnsupportedError);
+  });
+
+  test("throws PluginMergeBaselineError when no fingerprint was recorded", async () => {
+    // GIVEN an install whose sidecar records no fingerprint (older install)
+    installMergeCopy("level-up", OURS, SHA_A, null);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
+
+    // WHEN a merge strategy is requested
+    // THEN the baseline cannot be trusted, so the merge is refused
+    await expect(
+      upgradePlugin(
+        { name: "level-up", strategy: "ours" },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginMergeBaselineError);
+  });
+
+  test("throws PluginMergeBaselineError when the re-materialized base drifts from the recorded fingerprint", async () => {
+    // GIVEN an install whose recorded fingerprint describes a tree that differs
+    // from what re-materializing the install commit produces (an adapter
+    // overlay that moved since install)
+    installMergeCopy("level-up", OURS, SHA_A, {
+      "common.txt": "totally different baseline\n",
+    });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
+
+    // WHEN a merge strategy is requested
+    // THEN the baseline is rejected rather than producing a corrupt merge
+    await expect(
+      upgradePlugin(
+        { name: "level-up", strategy: "theirs" },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginMergeBaselineError);
+  });
+});