@vellumai/assistant 0.8.11 → 0.8.12-staging.1

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

@@ -0,0 +1,183 @@
+/**
+ * Tests for {@link parsePluginArtifact} — the `vellum.artifact` descriptor
+ * reader. A descriptor is surfaced only when both fields are well-formed
+ * (https URL + 64-hex sha256); every malformed or partial shape is "no
+ * artifact yet" (`null`) so callers never offer an unverifiable download.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { parsePluginArtifact } from "../plugin-artifact.js";
+
+const VALID_SHA = "a".repeat(64);
+
+describe("parsePluginArtifact", () => {
+  test("returns the descriptor when url + sha256 are well-formed", () => {
+    // GIVEN a package.json with a complete vellum.artifact block
+    const pkg = {
+      vellum: {
+        artifact: {
+          url: "https://example.com/releases/v1.0.0/App.dmg",
+          sha256: VALID_SHA,
+        },
+      },
+    };
+
+    // WHEN we parse it
+    const artifact = parsePluginArtifact(pkg);
+
+    // THEN both fields come through unchanged
+    expect(artifact).toEqual({
+      url: "https://example.com/releases/v1.0.0/App.dmg",
+      sha256: VALID_SHA,
+    });
+  });
+
+  test("surfaces an optional label when the plugin names the download", () => {
+    // GIVEN a block that labels its artifact (e.g. for multi-artifact plugins)
+    const pkg = {
+      vellum: {
+        artifact: {
+          url: "https://example.com/App.dmg",
+          sha256: VALID_SHA,
+          label: "Download for macOS",
+        },
+      },
+    };
+
+    // WHEN we parse it
+    const artifact = parsePluginArtifact(pkg);
+
+    // THEN the label comes through alongside url + sha256
+    expect(artifact).toEqual({
+      url: "https://example.com/App.dmg",
+      sha256: VALID_SHA,
+      label: "Download for macOS",
+    });
+  });
+
+  test("trims a label and drops it when blank, keeping the descriptor", () => {
+    // GIVEN a descriptor whose label is whitespace-only
+    const pkg = {
+      vellum: {
+        artifact: {
+          url: "https://example.com/App.dmg",
+          sha256: VALID_SHA,
+          label: "   ",
+        },
+      },
+    };
+
+    // WHEN we parse it
+    const artifact = parsePluginArtifact(pkg);
+
+    // THEN the blank label is dropped but the artifact still surfaces
+    expect(artifact).toEqual({
+      url: "https://example.com/App.dmg",
+      sha256: VALID_SHA,
+    });
+  });
+
+  test("ignores a non-string label without dropping the descriptor", () => {
+    // GIVEN a label of the wrong type
+    const pkg = {
+      vellum: {
+        artifact: {
+          url: "https://example.com/App.dmg",
+          sha256: VALID_SHA,
+          label: 42,
+        },
+      },
+    };
+
+    // WHEN we parse it
+    const artifact = parsePluginArtifact(pkg);
+
+    // THEN the bad label is ignored but url + sha256 still come through
+    expect(artifact).toEqual({
+      url: "https://example.com/App.dmg",
+      sha256: VALID_SHA,
+    });
+  });
+
+  test("ignores extra fields inside the artifact block", () => {
+    // GIVEN a block carrying fields beyond url + sha256
+    const pkg = {
+      vellum: {
+        artifact: {
+          url: "https://example.com/App.dmg",
+          sha256: VALID_SHA,
+          platform: "macos",
+          minOS: "13.0",
+        },
+      },
+    };
+
+    // WHEN we parse it
+    const artifact = parsePluginArtifact(pkg);
+
+    // THEN only the two recognised fields are surfaced
+    expect(artifact).toEqual({
+      url: "https://example.com/App.dmg",
+      sha256: VALID_SHA,
+    });
+  });
+
+  test.each([
+    ["no vellum block", { name: "x" }],
+    ["no artifact block", { vellum: {} }],
+    [
+      "empty sha256 (bootstrap placeholder)",
+      {
+        vellum: {
+          artifact: { url: "https://example.com/App.dmg", sha256: "" },
+        },
+      },
+    ],
+    [
+      "sha256 too short",
+      {
+        vellum: {
+          artifact: { url: "https://example.com/App.dmg", sha256: "abc" },
+        },
+      },
+    ],
+    [
+      "sha256 with uppercase hex",
+      {
+        vellum: {
+          artifact: {
+            url: "https://example.com/App.dmg",
+            sha256: "A".repeat(64),
+          },
+        },
+      },
+    ],
+    [
+      "non-https url",
+      {
+        vellum: {
+          artifact: { url: "http://example.com/App.dmg", sha256: VALID_SHA },
+        },
+      },
+    ],
+    ["missing url", { vellum: { artifact: { sha256: VALID_SHA } } }],
+    ["artifact is not an object", { vellum: { artifact: "App.dmg" } }],
+    ["vellum is an array", { vellum: [] }],
+  ])("returns null for %s", (_label, pkg) => {
+    // WHEN we parse a malformed / partial descriptor
+    // THEN nothing is surfaced
+    expect(parsePluginArtifact(pkg)).toBeNull();
+  });
+
+  test.each([
+    ["null", null],
+    ["a string", "not-a-package"],
+    ["an array", []],
+    ["a number", 42],
+  ])("returns null when package.json is %s", (_label, value) => {
+    // WHEN we parse a non-object package.json value
+    // THEN nothing is surfaced
+    expect(parsePluginArtifact(value)).toBeNull();
+  });
+});

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

@@ -372,4 +372,162 @@ describe("getPluginDetails", () => {
       ),
     ).rejects.toThrow();
   });
+
+  test("surfaces a well-formed vellum.artifact from the repo package.json", async () => {
+    // GIVEN an external plugin whose repo package.json declares a complete
+    // vellum.artifact (https url + 64-hex sha256)
+    const sha = "a".repeat(64);
+    const fetch = makeFetch({
+      marketplace: {
+        name: "vellum",
+        plugins: [
+          {
+            name: "dynamic-notch",
+            source: {
+              source: "github",
+              repo: "example-org/dynamic-notch",
+              ref: "1111111111111111111111111111111111111111",
+            },
+          },
+        ],
+      },
+      listings: {
+        "example-org/dynamic-notch": [
+          fileEntry("package.json", "raw://notch/pkg"),
+        ],
+      },
+      raw: {
+        "raw://notch/pkg": JSON.stringify({
+          version: "1.0.0",
+          vellum: {
+            artifact: {
+              url: "https://example.com/releases/v1.0.0/App.dmg",
+              sha256: sha,
+              label: "Download for macOS",
+            },
+          },
+        }),
+      },
+    });
+
+    // WHEN we resolve the detail view
+    const details = await getPluginDetails(
+      { name: "dynamic-notch" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the artifact descriptor is surfaced, including its optional label
+    expect(details.artifact).toEqual({
+      url: "https://example.com/releases/v1.0.0/App.dmg",
+      sha256: sha,
+      label: "Download for macOS",
+    });
+  });
+
+  test("an installed copy's artifact wins over the repo's", async () => {
+    // GIVEN an installed copy whose package.json declares its own artifact
+    const localSha = "b".repeat(64);
+    const remoteSha = "c".repeat(64);
+    const target = join(workspace, "dynamic-notch");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(
+      join(target, "package.json"),
+      JSON.stringify({
+        vellum: {
+          artifact: {
+            url: "https://example.com/local/App.dmg",
+            sha256: localSha,
+          },
+        },
+      }),
+    );
+
+    // AND a marketplace entry + repo package.json declaring a different artifact
+    const fetch = makeFetch({
+      marketplace: {
+        name: "vellum",
+        plugins: [
+          {
+            name: "dynamic-notch",
+            source: {
+              source: "github",
+              repo: "example-org/dynamic-notch",
+              ref: "1111111111111111111111111111111111111111",
+            },
+          },
+        ],
+      },
+      listings: {
+        "example-org/dynamic-notch": [
+          fileEntry("package.json", "raw://notch/pkg"),
+        ],
+      },
+      raw: {
+        "raw://notch/pkg": JSON.stringify({
+          vellum: {
+            artifact: {
+              url: "https://example.com/remote/App.dmg",
+              sha256: remoteSha,
+            },
+          },
+        }),
+      },
+    });
+
+    // WHEN we resolve the detail view
+    const details = await getPluginDetails(
+      { name: "dynamic-notch" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the installed copy's artifact wins
+    expect(details.artifact).toEqual({
+      url: "https://example.com/local/App.dmg",
+      sha256: localSha,
+    });
+  });
+
+  test("treats a placeholder sha256 as no artifact yet", async () => {
+    // GIVEN a repo package.json with a url but an empty (placeholder) sha256 —
+    // the bootstrap state before a release workflow fills the digest in
+    const fetch = makeFetch({
+      marketplace: {
+        name: "vellum",
+        plugins: [
+          {
+            name: "dynamic-notch",
+            source: {
+              source: "github",
+              repo: "example-org/dynamic-notch",
+              ref: "1111111111111111111111111111111111111111",
+            },
+          },
+        ],
+      },
+      listings: {
+        "example-org/dynamic-notch": [
+          fileEntry("package.json", "raw://notch/pkg"),
+        ],
+      },
+      raw: {
+        "raw://notch/pkg": JSON.stringify({
+          vellum: {
+            artifact: {
+              url: "https://example.com/releases/v1.0.0/App.dmg",
+              sha256: "",
+            },
+          },
+        }),
+      },
+    });
+
+    // WHEN we resolve the detail view
+    const details = await getPluginDetails(
+      { name: "dynamic-notch" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN no artifact is surfaced (a client must not offer an unverifiable download)
+    expect(details.artifact).toBeNull();
+  });
 });

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);
+  });
+});