@vellumai/assistant 0.8.11 → 0.8.12-staging.2

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

@@ -0,0 +1,245 @@
+/**
+ * Tests for the plugin content-fingerprint helpers.
+ *
+ * Each test materializes a real tree under a temp directory, fingerprints it,
+ * then mutates the tree and asserts the comparison reports the expected
+ * modified / added / removed paths. The sidecar is exercised through the
+ * `exclude` argument so it never counts as a local addition.
+ */
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  compareFingerprint,
+  computeContentHash,
+  computeFingerprint,
+  parseFingerprint,
+} from "../plugin-fingerprint.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "plugin-fingerprint-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function write(rel: string, contents: string): void {
+  const abs = join(root, rel);
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(abs, contents);
+}
+
+describe("computeFingerprint", () => {
+  test("digests every regular file with POSIX-relative keys", () => {
+    // GIVEN a tree with a nested file
+    write("package.json", "{}");
+    write("src/index.ts", "export const x = 1;");
+
+    // WHEN it is fingerprinted
+    const fp = computeFingerprint(root);
+
+    // THEN every file is keyed by its forward-slash relative path
+    expect(Object.keys(fp.files).sort()).toEqual([
+      "package.json",
+      "src/index.ts",
+    ]);
+    expect(fp.algorithm).toBe("sha256");
+    expect(fp.files["src/index.ts"]).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("excludes named top-level entries (the sidecar)", () => {
+    // GIVEN a tree containing the provenance sidecar
+    write("package.json", "{}");
+    write("install-meta.json", '{"name":"x"}');
+
+    // WHEN it is fingerprinted excluding the sidecar
+    const fp = computeFingerprint(root, ["install-meta.json"]);
+
+    // THEN the sidecar is not part of the digest map
+    expect(Object.keys(fp.files)).toEqual(["package.json"]);
+  });
+
+  test("skips symlinks", () => {
+    // GIVEN a tree with a real file and a symlink to it
+    write("real.txt", "hello");
+    symlinkSync(join(root, "real.txt"), join(root, "link.txt"));
+
+    // WHEN it is fingerprinted
+    const fp = computeFingerprint(root);
+
+    // THEN only the regular file is digested
+    expect(Object.keys(fp.files)).toEqual(["real.txt"]);
+  });
+});
+
+describe("compareFingerprint", () => {
+  test("reports clean when the tree is unchanged", () => {
+    // GIVEN a fingerprinted tree
+    write("a.txt", "one");
+    write("b.txt", "two");
+    const baseline = computeFingerprint(root);
+
+    // WHEN it is compared against itself untouched
+    const diff = compareFingerprint(root, baseline);
+
+    // THEN nothing is reported as changed
+    expect(diff.clean).toBe(true);
+    expect(diff.modified).toEqual([]);
+    expect(diff.added).toEqual([]);
+    expect(diff.removed).toEqual([]);
+  });
+
+  test("classifies modified, added, and removed files", () => {
+    // GIVEN a baseline of two files
+    write("keep.txt", "keep");
+    write("change.txt", "before");
+    const baseline = computeFingerprint(root);
+
+    // AND the tree is edited: one file changed, one added, one removed
+    write("change.txt", "after");
+    write("new.txt", "fresh");
+    rmSync(join(root, "keep.txt"));
+
+    // WHEN the tree is compared against the baseline
+    const diff = compareFingerprint(root, baseline);
+
+    // THEN each change is bucketed correctly
+    expect(diff.clean).toBe(false);
+    expect(diff.modified).toEqual(["change.txt"]);
+    expect(diff.added).toEqual(["new.txt"]);
+    expect(diff.removed).toEqual(["keep.txt"]);
+  });
+
+  test("does not count an excluded sidecar as an addition", () => {
+    // GIVEN a baseline computed with the sidecar excluded
+    write("package.json", "{}");
+    const baseline = computeFingerprint(root, ["install-meta.json"]);
+
+    // AND the sidecar exists on disk (as it would post-install)
+    write("install-meta.json", '{"name":"x"}');
+
+    // WHEN compared with the same exclusion
+    const diff = compareFingerprint(root, baseline, ["install-meta.json"]);
+
+    // THEN the tree is still clean
+    expect(diff.clean).toBe(true);
+  });
+});
+
+describe("parseFingerprint", () => {
+  test("round-trips a computed fingerprint through JSON", () => {
+    // GIVEN a computed fingerprint serialized to JSON
+    write("a.txt", "one");
+    const fp = computeFingerprint(root);
+
+    // WHEN it is parsed back
+    const parsed = parseFingerprint(JSON.parse(JSON.stringify(fp)));
+
+    // THEN it matches the original
+    expect(parsed).toEqual(fp);
+  });
+
+  test.each([
+    ["a non-object", 42],
+    ["a wrong algorithm", { algorithm: "md5", files: {} }],
+    ["a missing files map", { algorithm: "sha256" }],
+    ["a non-string digest", { algorithm: "sha256", files: { a: 1 } }],
+  ])("returns null for %s", (_label, value) => {
+    // WHEN a malformed value is parsed
+    const parsed = parseFingerprint(value);
+
+    // THEN it is rejected leniently
+    expect(parsed).toBeNull();
+  });
+});
+
+describe("computeContentHash", () => {
+  test("returns a v2-prefixed sha256 digest over the tree", () => {
+    // GIVEN a tree with a nested file
+    write("package.json", "{}");
+    write("src/index.ts", "export const x = 1;");
+
+    // WHEN the aggregate content hash is computed
+    const hash = computeContentHash(root);
+
+    // THEN it is the versioned sha256 hex format skills also use
+    expect(hash).toMatch(/^v2:[0-9a-f]{64}$/);
+  });
+
+  test("is independent of filesystem creation order", () => {
+    // GIVEN two trees with identical contents written in different orders
+    write("b.txt", "two");
+    write("a.txt", "one");
+    const first = computeContentHash(root);
+
+    rmSync(root, { recursive: true, force: true });
+    mkdirSync(root, { recursive: true });
+    write("a.txt", "one");
+    write("b.txt", "two");
+
+    // WHEN both are hashed
+    const second = computeContentHash(root);
+
+    // THEN the digests match — the walk visits files in path order
+    expect(second).toBe(first);
+  });
+
+  test("changes when any file content changes", () => {
+    // GIVEN a baseline hash
+    write("a.txt", "one");
+    const baseline = computeContentHash(root);
+
+    // AND a file is edited
+    write("a.txt", "two");
+
+    // WHEN the hash is recomputed
+    const updated = computeContentHash(root);
+
+    // THEN it differs from the baseline
+    expect(updated).not.toBe(baseline);
+  });
+
+  test("excludes named top-level entries (the sidecar)", () => {
+    // GIVEN a tree and a baseline computed with the sidecar excluded
+    write("package.json", "{}");
+    const baseline = computeContentHash(root, ["install-meta.json"]);
+
+    // AND the sidecar later exists on disk (as it would post-install)
+    write("install-meta.json", '{"name":"x"}');
+
+    // WHEN the hash is recomputed with the same exclusion
+    const after = computeContentHash(root, ["install-meta.json"]);
+
+    // THEN the sidecar does not perturb the digest
+    expect(after).toBe(baseline);
+  });
+
+  test("is not collision-prone across path/content boundaries", () => {
+    // GIVEN two trees whose concatenated path+content bytes would collide
+    // without length-prefixing ("ab" + "c" vs "a" + "bc")
+    write("ab", "c");
+    const first = computeContentHash(root);
+
+    rmSync(root, { recursive: true, force: true });
+    mkdirSync(root, { recursive: true });
+    write("a", "bc");
+
+    // WHEN both are hashed
+    const second = computeContentHash(root);
+
+    // THEN the length-prefixed scheme keeps them distinct
+    expect(second).not.toBe(first);
+  });
+});

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

@@ -0,0 +1,307 @@
+/**
+ * Tests for {@link upgradePlugin}.
+ *
+ * An upgrade is drift detection (the same exact SHA comparison
+ * {@link inspectPlugin} performs) followed by a forced re-install at the
+ * marketplace pin. The marketplace + GitHub Contents API are replaced with an
+ * in-memory fixture passed via `fetch`, the clone is replaced with a fake
+ * {@link GitRunner} that materializes a tree, and the install target is a real
+ * temp directory passed via `workspacePluginsDir` — no globals are patched.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  type FetchLike,
+  type GitRunner,
+  PluginSourceUnavailableError,
+} from "../install-from-github.js";
+import { PluginNotInstalledError } from "../uninstall-plugin.js";
+import { PluginNotUpgradableError, upgradePlugin } from "../upgrade-plugin.js";
+
+const SHA_A = "a".repeat(40);
+const SHA_B = "b".repeat(40);
+const CANON_REPO = "vellum-ai/vellum-assistant";
+const MANIFEST_URL = `https://api.github.com/repos/${CANON_REPO}/contents/plugins/marketplace.json`;
+const CONTENTS = `https://api.github.com/repos/${CANON_REPO}/contents/`;
+
+/** A marketplace manifest pinning `name` to `ref`. */
+function manifestWith(name: string, ref: string): unknown {
+  return {
+    name: "vellum",
+    plugins: [
+      {
+        name,
+        source: { source: "github", repo: `example-org/${name}`, ref },
+        description: "A test plugin.",
+        category: "developer",
+        license: "MIT",
+      },
+    ],
+  };
+}
+
+/**
+ * Build a `fetch` that serves the marketplace manifest and answers the GitHub
+ * Contents API listing (used by the adapter-stub lookup) with a 404, so the
+ * clone is treated as a raw external tree. `manifest: undefined` answers the
+ * manifest with 404; `manifestStatus` overrides the manifest status to
+ * simulate a transient marketplace failure.
+ */
+function makeFetch(opts: {
+  manifest?: unknown;
+  manifestStatus?: number;
+}): FetchLike {
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.startsWith(MANIFEST_URL)) {
+      if (opts.manifestStatus !== undefined && opts.manifestStatus !== 200) {
+        return new Response("manifest unavailable", {
+          status: opts.manifestStatus,
+        });
+      }
+      if (opts.manifest === undefined) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(JSON.stringify(opts.manifest), { status: 200 });
+    }
+    // No adapter stub: the Contents API listing for plugins/<name> is empty.
+    if (url.startsWith(CONTENTS)) {
+      return new Response("not found", { status: 404 });
+    }
+    return new Response(`unexpected url: ${url}`, { status: 500 });
+  }) as FetchLike;
+}
+
+/** A fake clone that materializes one file and reports `commit` at HEAD. */
+function fakeGitRunner(commit: string, calls?: string[][]): GitRunner {
+  return async (args, { cwd }) => {
+    calls?.push([...args]);
+    switch (args[0]) {
+      case "fetch": {
+        mkdirSync(join(cwd, ".git"), { recursive: true });
+        writeFileSync(join(cwd, ".git", "config"), "[core]\n");
+        writeFileSync(join(cwd, "package.json"), '{"name":"level-up"}');
+        return { stdout: "" };
+      }
+      case "rev-parse":
+        return { stdout: `${commit}\n` };
+      default:
+        return { stdout: "" };
+    }
+  };
+}
+
+/** A git runner that fails the test if any git command runs. */
+const unusedGitRunner: GitRunner = async (args) => {
+  throw new Error(`git should not run for this upgrade: ${args.join(" ")}`);
+};
+
+/** Materialize an installed plugin copy with an optional provenance sidecar. */
+function installCopy(
+  pluginsDir: string,
+  name: string,
+  sidecar: { commit: string } | null,
+): void {
+  const dir = join(pluginsDir, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name, version: "0.1.0", description: "Installed copy." }),
+  );
+  if (sidecar !== null) {
+    writeFileSync(
+      join(dir, "install-meta.json"),
+      JSON.stringify({
+        origin: "vellum",
+        name,
+        source: {
+          kind: "github",
+          owner: "example-org",
+          repo: name,
+          ref: sidecar.commit,
+        },
+        commit: sidecar.commit,
+        installedAt: "2026-06-10T12:00:00.000Z",
+      }),
+    );
+  }
+}
+
+/** Read the commit recorded in a copy's provenance sidecar, if present. */
+function sidecarCommit(pluginsDir: string, name: string): string | null {
+  const path = join(pluginsDir, name, "install-meta.json");
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf-8")).commit ?? null;
+}
+
+let ws: string;
+let pluginsDir: string;
+
+beforeEach(() => {
+  ws = mkdtempSync(join(tmpdir(), "upgrade-plugin-"));
+  pluginsDir = join(ws, "plugins");
+  mkdirSync(pluginsDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(ws, { recursive: true, force: true });
+});
+
+describe("upgradePlugin", () => {
+  test("upgrades to the marketplace pin when it has advanced", async () => {
+    // GIVEN an installed copy pinned to SHA_A
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    // AND the marketplace now pins SHA_B
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    // WHEN the plugin is upgraded
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it reports the move from the old commit to the pin
+    expect(result.outcome).toBe("upgraded");
+    expect(result.fromCommit).toBe(SHA_A);
+    expect(result.toCommit).toBe(SHA_B);
+    expect(result.fileCount).toBeGreaterThan(0);
+    // AND the new pin is recorded in the provenance sidecar on disk
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_B);
+  });
+
+  test("is a no-op when the installed commit already equals the pin", async () => {
+    // GIVEN an installed copy already pinned to SHA_A
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    // AND the marketplace pins the same SHA_A
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_A) });
+
+    // WHEN the plugin is upgraded (git must never run)
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it reports already-up-to-date and makes no changes
+    expect(result.outcome).toBe("already-up-to-date");
+    expect(result.fileCount).toBeNull();
+    expect(result.toCommit).toBe(SHA_A);
+  });
+
+  test("a dry run reports the move without modifying the install", async () => {
+    // GIVEN an installed copy pinned to SHA_A and a marketplace pin of SHA_B
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+
+    // WHEN the plugin is upgraded with dryRun (git must never run)
+    const result = await upgradePlugin(
+      { name: "level-up", dryRun: true },
+      { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it reports what would change but leaves the install untouched
+    expect(result.outcome).toBe("would-upgrade");
+    expect(result.dryRun).toBe(true);
+    expect(result.fileCount).toBeNull();
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+
+  test("re-pins and records provenance for an install with none", async () => {
+    // GIVEN an installed copy with no provenance sidecar
+    installCopy(pluginsDir, "level-up", null);
+    // AND the marketplace pins SHA_B
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    // WHEN the plugin is upgraded
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it upgrades, flags the missing provenance, and records the new pin
+    expect(result.outcome).toBe("upgraded");
+    expect(result.fromCommit).toBeNull();
+    expect(result.provenanceWasUnknown).toBe(true);
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_B);
+  });
+
+  test("throws PluginNotInstalledError when nothing is installed", async () => {
+    // GIVEN no installed copy, though the marketplace has an entry
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+
+    // WHEN an upgrade is attempted
+    // THEN it refuses because there is no install to advance
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotInstalledError);
+  });
+
+  test("throws PluginNotUpgradableError when not in the marketplace", async () => {
+    // GIVEN an installed copy but an empty marketplace catalog
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: undefined });
+
+    // WHEN an upgrade is attempted
+    // THEN there is no pin to advance to
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotUpgradableError);
+  });
+
+  test("throws PluginSourceUnavailableError when the marketplace is unreachable", async () => {
+    // GIVEN an installed copy and a marketplace fetch that fails transiently
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifestStatus: 500 });
+
+    // WHEN an upgrade is attempted
+    // THEN the outage is surfaced as a retryable source-unavailable error
+    // (distinct from the permanent no-marketplace-entry conflict), since the
+    // same request can succeed once the catalog recovers
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginSourceUnavailableError);
+  });
+
+  test("preserves the existing install when the re-install clone fails", async () => {
+    // GIVEN an installed copy pinned to SHA_A and an advanced marketplace pin
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    // AND a clone that fails mid-fetch
+    const failingGit: GitRunner = async (args) => {
+      if (args[0] === "fetch") throw new Error("network down");
+      return { stdout: "" };
+    };
+
+    // WHEN the upgrade is attempted
+    // THEN it surfaces the clone failure
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: failingGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toThrow("network down");
+    // AND the previously installed copy is left intact at its old pin
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+});