@vellumai/assistant 0.8.11 → 0.8.12-staging.2

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

@@ -0,0 +1,318 @@
+/**
+ * Tests for {@link inspectPlugin}.
+ *
+ * The marketplace fetch is replaced with an in-memory fixture passed via the
+ * `fetch` dependency, and the installed-copy path is exercised against a real
+ * temp directory passed via `workspacePluginsDir` — no globals are monkeypatched.
+ * Drift is the exact comparison of the provenance sidecar's commit against the
+ * marketplace pin, so the fixtures vary those two SHAs.
+ */
+
+import { mkdirSync, mkdtempSync, 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 {
+  inspectPlugin,
+  PluginInspectNotFoundError,
+} from "../inspect-plugin.js";
+import type { FetchLike } from "../install-from-github.js";
+import { computeFingerprint } from "../plugin-fingerprint.js";
+
+const SHA_A = "a".repeat(40);
+const SHA_B = "b".repeat(40);
+
+/** A marketplace manifest object with a single entry for `name`. */
+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",
+        homepage: `https://github.com/example-org/${name}`,
+        license: "MIT",
+      },
+    ],
+  };
+}
+
+/**
+ * Build a `fetch` that serves the marketplace manifest. `marketplace:
+ * undefined` answers 404 (empty catalog); `fail: true` rejects with a network
+ * error. Anything else surfaces a 500 so test bugs are loud.
+ */
+function makeFetch(opts: { marketplace?: unknown; fail?: boolean }): FetchLike {
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("marketplace.json")) {
+      if (opts.fail) throw new Error("network down");
+      if (opts.marketplace === undefined) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(JSON.stringify(opts.marketplace), { status: 200 });
+    }
+    return new Response("unexpected url: " + url, { status: 500 });
+  }) as FetchLike;
+}
+
+/** Materialize an installed plugin copy with an optional provenance sidecar. */
+function installPlugin(
+  workspace: string,
+  name: string,
+  opts: {
+    version?: string;
+    sidecar?: { commit?: string | null; ref?: string } | null;
+    /** Embed a content fingerprint of the materialized tree in the sidecar. */
+    fingerprint?: boolean;
+  } = {},
+): void {
+  const dir = join(workspace, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({
+      name,
+      version: opts.version ?? "0.1.0",
+      description: "Installed copy.",
+    }),
+  );
+  if (opts.sidecar !== null) {
+    const sidecar = opts.sidecar ?? { commit: SHA_A };
+    // Mirror install: fingerprint the tree before the sidecar is written so it
+    // is not part of its own baseline.
+    const fingerprint = opts.fingerprint
+      ? computeFingerprint(dir, ["install-meta.json"])
+      : undefined;
+    writeFileSync(
+      join(dir, "install-meta.json"),
+      JSON.stringify({
+        origin: "vellum",
+        name,
+        source: {
+          kind: "github",
+          owner: "example-org",
+          repo: name,
+          ref: sidecar.ref ?? sidecar.commit ?? SHA_A,
+        },
+        commit: sidecar.commit ?? undefined,
+        installedAt: "2026-06-10T12:00:00.000Z",
+        fingerprint,
+      }),
+    );
+  }
+}
+
+let workspace: string;
+
+beforeEach(() => {
+  workspace = mkdtempSync(join(tmpdir(), "inspect-plugin-"));
+});
+
+afterEach(() => {
+  rmSync(workspace, { recursive: true, force: true });
+});
+
+describe("inspectPlugin", () => {
+  test("reports up-to-date when the installed commit equals the marketplace pin", async () => {
+    // GIVEN an installed plugin pinned to the same commit the marketplace pins
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the status is up-to-date and both sides resolve the same commit
+    expect(result.status).toBe("up-to-date");
+    expect(result.installed).toBe(true);
+    expect(result.local?.commit).toBe(SHA_A);
+    expect(result.remote?.commit).toBe(SHA_A);
+    // AND local + remote metadata are surfaced
+    expect(result.local?.version).toBe("0.1.0");
+    expect(result.remote?.repo).toBe("example-org/level-up");
+    expect(result.remote?.license).toBe("MIT");
+  });
+
+  test("reports update-available when the marketplace pin has advanced", async () => {
+    // GIVEN an installed plugin whose commit differs from the marketplace pin
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_B) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN drift is reported with both commits
+    expect(result.status).toBe("update-available");
+    expect(result.local?.commit).toBe(SHA_A);
+    expect(result.remote?.commit).toBe(SHA_B);
+  });
+
+  test("falls back to the sidecar ref when no commit was recorded", async () => {
+    // GIVEN a sidecar with no commit but a full-SHA ref equal to the pin
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: null, ref: SHA_A },
+    });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the ref stands in for the commit and the status is up-to-date
+    expect(result.status).toBe("up-to-date");
+    expect(result.local?.commit).toBe(SHA_A);
+  });
+
+  test("reports unknown-provenance when installed without a resolvable commit", async () => {
+    // GIVEN an installed copy with no provenance sidecar at all
+    installPlugin(workspace, "level-up", { sidecar: null });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the commit cannot be compared
+    expect(result.status).toBe("unknown-provenance");
+    expect(result.local?.commit).toBeNull();
+    expect(result.remote?.commit).toBe(SHA_A);
+  });
+
+  test("reports not-in-marketplace when installed but no entry claims the name", async () => {
+    // GIVEN an installed plugin and an empty catalog
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: undefined });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN there is no remote to compare against
+    expect(result.status).toBe("not-in-marketplace");
+    expect(result.installed).toBe(true);
+    expect(result.remote).toBeNull();
+  });
+
+  test("reports not-installed but previews the marketplace entry", async () => {
+    // GIVEN a marketplace entry with no local copy installed
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_B) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the remote metadata previews what would be installed
+    expect(result.status).toBe("not-installed");
+    expect(result.installed).toBe(false);
+    expect(result.local).toBeNull();
+    expect(result.remote?.commit).toBe(SHA_B);
+  });
+
+  test("reports remote-unavailable when the marketplace cannot be reached", async () => {
+    // GIVEN an installed plugin and a failing marketplace fetch
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ fail: true });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN local info is still reported alongside the fetch error
+    expect(result.status).toBe("remote-unavailable");
+    expect(result.local?.commit).toBe(SHA_A);
+    expect(result.remote).toBeNull();
+    expect(result.remoteError).toContain("network down");
+  });
+
+  test("reports no local changes when the on-disk tree matches the fingerprint", async () => {
+    // GIVEN an installed plugin with a recorded content fingerprint, untouched
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: SHA_A },
+      fingerprint: true,
+    });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the local copy is reported clean against its baseline
+    expect(result.local?.localChanges?.clean).toBe(true);
+    expect(result.local?.localChanges?.modified).toEqual([]);
+  });
+
+  test("detects a locally modified file against the fingerprint", async () => {
+    // GIVEN an installed plugin with a recorded fingerprint
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: SHA_A },
+      fingerprint: true,
+    });
+
+    // AND a tracked file is edited after install
+    writeFileSync(
+      join(workspace, "level-up", "package.json"),
+      JSON.stringify({ name: "level-up", version: "9.9.9" }),
+    );
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the edited file surfaces as a local modification
+    expect(result.local?.localChanges?.clean).toBe(false);
+    expect(result.local?.localChanges?.modified).toEqual(["package.json"]);
+  });
+
+  test("reports unknown local changes when no fingerprint was recorded", async () => {
+    // GIVEN an install whose sidecar predates fingerprinting
+    installPlugin(workspace, "level-up", { sidecar: { commit: SHA_A } });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN modification cannot be determined
+    expect(result.local).not.toBeNull();
+    expect(result.local?.localChanges).toBeNull();
+  });
+
+  test("throws when the plugin is neither installed nor in the marketplace", async () => {
+    // GIVEN no local copy and an empty catalog
+    const fetch = makeFetch({ marketplace: undefined });
+
+    // WHEN/THEN inspecting a missing plugin rejects with a not-found error
+    await expect(
+      inspectPlugin(
+        { name: "ghost" },
+        { fetch, workspacePluginsDir: workspace },
+      ),
+    ).rejects.toBeInstanceOf(PluginInspectNotFoundError);
+  });
+});

package/src/cli/lib/__tests__/install-from-github.test.ts

@@ -371,16 +371,23 @@ describe("installPlugin — marketplace resolution", () => {
       "https://github.com/JuliusBrussee/caveman.git",
     );
 
-    // AND a provenance manifest records the github source + commit.
-    const manifest = JSON.parse(
-      readFileSync(join(target, ".vellum-plugin.json"), "utf-8"),
+    // AND an install-meta sidecar records origin + github source + commit.
+    const meta = JSON.parse(
+      readFileSync(join(target, "install-meta.json"), "utf-8"),
     );
-    expect(manifest.source.kind).toBe("github");
-    expect(manifest.source.owner).toBe("JuliusBrussee");
-    expect(manifest.source.ref).toBe(
-      "63a91ecadbf4c4719a4602a5abb00883f9966034",
-    );
-    expect(manifest.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+    expect(meta.origin).toBe("vellum");
+    expect(meta.sourceRepo).toBe("JuliusBrussee/caveman");
+    expect(meta.source.kind).toBe("github");
+    expect(meta.source.owner).toBe("JuliusBrussee");
+    expect(meta.source.ref).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+    expect(meta.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+
+    // AND both content digests baseline the materialized tree (excluding the
+    // sidecar) so later local edits are detectable.
+    expect(meta.fingerprint.algorithm).toBe("sha256");
+    expect(meta.fingerprint.files["package.json"]).toMatch(/^[0-9a-f]{64}$/);
+    expect(meta.fingerprint.files["install-meta.json"]).toBeUndefined();
+    expect(meta.contentHash).toMatch(/^v2:[0-9a-f]{64}$/);
   });
 
   test("refuses to install when the checked-out commit differs from the pinned SHA", async () => {

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