@vellumai/assistant 0.12.2-staging.4 → 0.12.2-staging.6

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

@@ -0,0 +1,169 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { FetchLike } from "../fetch-like.js";
+import { installPlugin, readInstallMeta } from "../install-from-github.js";
+import type { PluginCatalog } from "../search-plugins.js";
+import { upgradePlugin } from "../upgrade-plugin.js";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+function packageMaterializer(calls: string[]) {
+  return (path: string, version: string, destination: string): number => {
+    calls.push(`${path}@${version}`);
+    mkdirSync(destination, { recursive: true });
+    writeFileSync(
+      join(destination, "plugin.json"),
+      JSON.stringify({
+        $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+        name: "fathom",
+        version,
+      }),
+    );
+    writeFileSync(
+      join(destination, "mcp.json"),
+      JSON.stringify({
+        $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+        mcpServers: {
+          fathom: {
+            type: "streamable-http",
+            url: "https://api.fathom.ai/mcp",
+          },
+        },
+      }),
+    );
+    return 2;
+  };
+}
+
+function marketplaceFetch(version: string): FetchLike {
+  return (async () =>
+    new Response(
+      JSON.stringify({
+        name: "vellum-assistant",
+        plugins: [
+          {
+            name: "fathom",
+            source: {
+              source: "local",
+              path: "plugins/mcp-catalog/fathom",
+              version,
+            },
+          },
+        ],
+      }),
+      { status: 200 },
+    )) as FetchLike;
+}
+
+function localCatalog(version: string): PluginCatalog {
+  return {
+    ref: "bundled",
+    matches: [
+      {
+        name: "fathom",
+        path: `local:plugins/mcp-catalog/fathom@${version}`,
+        category: null,
+        source: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version,
+        },
+      },
+    ],
+  };
+}
+
+describe("bundled plugin upgrades", () => {
+  test("ignores a newer live manifest version the current binary cannot materialize", async () => {
+    const root = mkdtempSync(join(tmpdir(), "local-plugin-upgrade-"));
+    roots.push(root);
+    const pluginsDir = join(root, "plugins");
+    const calls: string[] = [];
+    const materializeLocalPackage = packageMaterializer(calls);
+
+    await installPlugin(
+      {
+        name: "fathom",
+        trustedSource: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version: "1.0.0",
+        },
+      },
+      {
+        fetch: marketplaceFetch("1.0.0"),
+        workspacePluginsDir: pluginsDir,
+        materializeLocalPackage,
+      },
+    );
+
+    const result = await upgradePlugin(
+      { name: "fathom" },
+      {
+        fetch: marketplaceFetch("9.0.0"),
+        workspacePluginsDir: pluginsDir,
+        materializeLocalPackage,
+        localCatalog: localCatalog("1.0.0"),
+        beforeSwap: async () => {},
+      },
+    );
+
+    expect(result.outcome).toBe("already-up-to-date");
+    expect(calls).toEqual(["plugins/mcp-catalog/fathom@1.0.0"]);
+  });
+
+  test("materializes the exact inspected path and version", async () => {
+    const root = mkdtempSync(join(tmpdir(), "local-plugin-upgrade-"));
+    roots.push(root);
+    const pluginsDir = join(root, "plugins");
+    const calls: string[] = [];
+    const materializeLocalPackage = packageMaterializer(calls);
+
+    await installPlugin(
+      {
+        name: "fathom",
+        trustedSource: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version: "1.0.0",
+        },
+      },
+      {
+        fetch: marketplaceFetch("1.0.0"),
+        workspacePluginsDir: pluginsDir,
+        materializeLocalPackage,
+      },
+    );
+
+    const result = await upgradePlugin(
+      { name: "fathom" },
+      {
+        fetch: marketplaceFetch("1.1.0"),
+        workspacePluginsDir: pluginsDir,
+        materializeLocalPackage,
+        localCatalog: localCatalog("1.1.0"),
+        beforeSwap: async () => {},
+      },
+    );
+
+    expect(result.outcome).toBe("upgraded");
+    expect(calls).toEqual([
+      "plugins/mcp-catalog/fathom@1.0.0",
+      "plugins/mcp-catalog/fathom@1.1.0",
+    ]);
+    expect(readInstallMeta(result.target)?.source).toEqual({
+      kind: "local",
+      path: "plugins/mcp-catalog/fathom",
+      version: "1.1.0",
+    });
+  });
+});

package/src/cli/lib/__tests__/plugin-catalog-cache.test.ts

@@ -20,10 +20,12 @@ import type { FetchLike } from "../fetch-like.js";
 import {
   getPluginCatalog,
   invalidatePluginCatalogCache,
+  mergePlatformCatalogWithBundledLocals,
   PLUGIN_CATALOG_CACHE_TTL_MS,
 } from "../plugin-catalog-cache.js";
 import { readBundledPluginCatalog } from "../plugin-catalog-local.js";
 import type { SearchPluginsDeps } from "../search-plugins.js";
+import type { PluginCatalog } from "../search-plugins.js";
 
 // A non-zero base time. Bun treats `setSystemTime(new Date(0))` as "reset to
 // the real clock", so the fake clock must start from a positive epoch.
@@ -166,3 +168,58 @@ describe("getPluginCatalog", () => {
     expect(result.ref).toBe("main");
   });
 });
+
+describe("mergePlatformCatalogWithBundledLocals", () => {
+  test("adds local packages while keeping a platform row on name collision", () => {
+    const platform: PluginCatalog = {
+      ref: "main",
+      matches: [
+        {
+          name: "fathom",
+          path: "github:provider/fathom@pin",
+          category: null,
+          source: {
+            kind: "github",
+            repo: "provider/fathom",
+            ref: "0".repeat(40),
+          },
+        },
+      ],
+    };
+    const bundled: PluginCatalog = {
+      ref: "bundled",
+      matches: [
+        {
+          name: "fathom",
+          path: "local:plugins/mcp-catalog/fathom@1.0.0",
+          category: null,
+          source: {
+            kind: "local",
+            path: "plugins/mcp-catalog/fathom",
+            version: "1.0.0",
+          },
+        },
+        {
+          name: "notion",
+          path: "local:plugins/mcp-catalog/notion@1.0.0",
+          category: null,
+          source: {
+            kind: "local",
+            path: "plugins/mcp-catalog/notion",
+            version: "1.0.0",
+          },
+        },
+      ],
+    };
+
+    const merged = mergePlatformCatalogWithBundledLocals(platform, bundled);
+
+    expect(merged.matches.map((match) => match.name)).toEqual([
+      "fathom",
+      "notion",
+    ]);
+    expect(merged.matches[0]?.source.kind).toBe("github");
+    expect(merged.matches[1]?.source.kind).toBe("local");
+    expect(merged.ref).toBe("main");
+  });
+});

package/src/cli/lib/__tests__/plugin-catalog-platform.test.ts

@@ -41,6 +41,15 @@ describe("fetchPluginCatalogFromPlatform", () => {
             homepage: "https://example.com",
             license: "MIT",
             icon: "🧠",
+            integration: {
+              kind: "mcp",
+              displayName: "Memory Graph",
+              documentationUrl: "https://example.com/docs",
+              verifiedAt: "2026-09-10",
+              verification: "documentation-only",
+              setup: { mode: "oauth", instructions: "Sign in." },
+              logo: "memory-graph.png",
+            },
             // dropped keys
             id: "abc",
             display_name: "Memory Graph",
@@ -69,6 +78,11 @@ describe("fetchPluginCatalogFromPlatform", () => {
       category: "productivity",
       homepage: "https://example.com",
       license: "MIT",
+      integration: {
+        kind: "mcp",
+        displayName: "Memory Graph",
+        logo: "memory-graph.png",
+      },
       source: {
         kind: "github",
         repo: "acme/memory-graph",

package/src/cli/lib/__tests__/plugin-catalog-resolve.test.ts

@@ -26,7 +26,9 @@ const FULL_SHA = "63a91ecadbf4c4719a4602a5abb00883f9966034";
 
 /** A synthetic catalog match with an overridable source. */
 function match(
-  source: Partial<PluginSearchMatch["source"]> = {},
+  source: Partial<
+    Extract<PluginSearchMatch["source"], { kind: "github" }>
+  > = {},
 ): PluginSearchMatch {
   return {
     name: "example",
@@ -37,12 +39,32 @@ function match(
 }
 
 describe("resolveSourceFromMatch", () => {
+  test("returns an exact bundled package path and version", () => {
+    expect(
+      resolveSourceFromMatch({
+        name: "fathom",
+        path: "local:plugins/mcp-catalog/fathom@1.0.0",
+        category: null,
+        source: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version: "1.0.0",
+        },
+      }),
+    ).toEqual({
+      kind: "local",
+      path: "plugins/mcp-catalog/fathom",
+      version: "1.0.0",
+    });
+  });
+
   test("returns owner/repo/path/ref for a full-SHA match", () => {
     expect(
       resolveSourceFromMatch(
         match({ repo: "acme/widget", path: "pkg/plugin" }),
       ),
     ).toEqual({
+      kind: "github",
       owner: "acme",
       repo: "widget",
       path: "pkg/plugin",
@@ -52,6 +74,7 @@ describe("resolveSourceFromMatch", () => {
 
   test('defaults path to "" when the source declares none', () => {
     expect(resolveSourceFromMatch(match())).toEqual({
+      kind: "github",
       owner: "acme",
       repo: "example",
       path: "",
@@ -66,6 +89,7 @@ describe("resolveSourceFromMatch", () => {
     // A repo-root entry (`path: ""` or absent) is valid — the clean-path gate
     // only applies to a non-empty path, so it must not be rejected.
     expect(resolveSourceFromMatch(match({ path }))).toEqual({
+      kind: "github",
       owner: "acme",
       repo: "example",
       path: "",
@@ -94,6 +118,7 @@ describe("resolveSourceFromMatch", () => {
 
   test("resolves a clean nested path", () => {
     expect(resolveSourceFromMatch(match({ path: "packages/plugin" }))).toEqual({
+      kind: "github",
       owner: "acme",
       repo: "example",
       path: "packages/plugin",
@@ -157,6 +182,7 @@ describe("catalog-backed resolvers (bundled, offline)", () => {
     expect(
       await resolvePluginSourceFromCatalog("caveman", rejectingDeps),
     ).toEqual({
+      kind: "github",
       owner: "JuliusBrussee",
       repo: "caveman",
       path: "",

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

@@ -108,12 +108,19 @@ function splitOnce(s: string, sep: string): [string, string] {
 }
 
 /** The bundled catalog entry for {@link name} — the source under test. */
-function bundledMatch(name: string): PluginSearchMatch {
+function bundledMatch(name: string): PluginSearchMatch & {
+  source: Extract<PluginSearchMatch["source"], { kind: "github" }>;
+} {
   const match = readBundledPluginCatalog().matches.find((m) => m.name === name);
   if (!match) {
     throw new Error(`bundled catalog has no entry for "${name}"`);
   }
-  return match;
+  if (match.source.kind !== "github") {
+    throw new Error(`bundled catalog entry "${name}" is not GitHub-backed`);
+  }
+  return match as PluginSearchMatch & {
+    source: Extract<PluginSearchMatch["source"], { kind: "github" }>;
+  };
 }
 
 const PNG_SIGNATURE = Buffer.from([

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

@@ -81,6 +81,24 @@ describe("fetchMarketplaceEntries", () => {
     expect(entries[1]!.source.path).toBe("packages/nested");
   });
 
+  test("skips an entry with an unknown future source kind", async () => {
+    const fetch = manifestFetch({
+      ...VALID_MANIFEST,
+      plugins: [
+        VALID_MANIFEST.plugins[0],
+        {
+          name: "future-plugin",
+          source: { source: "registry", package: "future-plugin" },
+        },
+        VALID_MANIFEST.plugins[1],
+      ],
+    });
+
+    const entries = await fetchMarketplaceEntries({ fetch }, { ref: "main" });
+
+    expect(entries.map((entry) => entry.name)).toEqual(["caveman", "nested"]);
+  });
+
   test("forwards the ref to the GitHub Contents API", async () => {
     // GIVEN a fixture that records the ref query parameter
     let seenRef: string | undefined;
@@ -334,6 +352,7 @@ describe("resolveMarketplaceSource", () => {
 
     // THEN the owner/repo split out and path defaults to repo root
     expect(resolved).toEqual({
+      kind: "github",
       owner: "JuliusBrussee",
       repo: "caveman",
       path: "",
@@ -348,6 +367,7 @@ describe("resolveMarketplaceSource", () => {
 
     // THEN the sub-path is preserved
     expect(resolved).toEqual({
+      kind: "github",
       owner: "acme",
       repo: "monorepo",
       path: "packages/nested",

package/src/cli/lib/__tests__/plugins-install-offline.test.ts

@@ -22,12 +22,19 @@ import {
 import { Command } from "commander";
 
 import type { InstallPluginOptions } from "../install-from-github.js";
+import type { PluginMatchSource } from "../search-plugins.js";
 
 const installPluginCalls: InstallPluginOptions[] = [];
 const platformInstallCalls: Array<{ name: string; force?: boolean }> = [];
 
 const realGithub = await import("../install-from-github.js");
 const realPlatform = await import("../install-from-platform.js");
+const realCatalogCache = await import("../plugin-catalog-cache.js");
+let platformCatalogSource: PluginMatchSource = {
+  kind: "github",
+  repo: "JuliusBrussee/caveman",
+  ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
+};
 
 mock.module("../install-from-github.js", () => ({
   ...realGithub,
@@ -59,6 +66,21 @@ mock.module("../install-from-platform.js", () => ({
   },
 }));
 
+mock.module("../plugin-catalog-cache.js", () => ({
+  ...realCatalogCache,
+  getPluginCatalog: async () => ({
+    ref: "main",
+    matches: [
+      {
+        name: BUNDLED_PLUGIN,
+        path: "fixture",
+        category: null,
+        source: platformCatalogSource,
+      },
+    ],
+  }),
+}));
+
 const { registerPluginsCommand } = await import("../../commands/plugins.js");
 
 /** A plugin known to live in the bundled marketplace manifest. */
@@ -90,6 +112,11 @@ describe("plugins install by name — disable-platform mode", () => {
     installPluginCalls.length = 0;
     platformInstallCalls.length = 0;
     process.exitCode = undefined;
+    platformCatalogSource = {
+      kind: "github",
+      repo: "JuliusBrussee/caveman",
+      ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
+    };
     spyOn(console, "log").mockImplementation(() => {});
     spyOn(console, "error").mockImplementation(() => {});
   });
@@ -156,4 +183,20 @@ describe("plugins install by name — disable-platform mode", () => {
     expect(platformInstallCalls[0]!.name).toBe(BUNDLED_PLUGIN);
     expect(process.exitCode).not.toBe(1);
   });
+
+  test("installs a platform-visible local package without the platform tar endpoint", async () => {
+    delete process.env.VELLUM_DISABLE_PLATFORM;
+    delete process.env.IS_PLATFORM;
+    platformCatalogSource = {
+      kind: "local",
+      path: "plugins/mcp-catalog/fathom",
+      version: "1.0.0",
+    };
+
+    await runInstall(BUNDLED_PLUGIN);
+
+    expect(platformInstallCalls).toHaveLength(0);
+    expect(installPluginCalls).toHaveLength(1);
+    expect(installPluginCalls[0]?.trustedSource).toEqual(platformCatalogSource);
+  });
 });

package/src/cli/lib/__tests__/search-plugins.test.ts

@@ -151,6 +151,37 @@ describe("assertValidSearchPattern", () => {
 });
 
 describe("marketplaceMatch", () => {
+  test("projects a bundled MCP package and its integration metadata", () => {
+    const match = marketplaceMatch({
+      name: "fathom",
+      source: {
+        source: "local",
+        path: "plugins/mcp-catalog/fathom",
+        version: "1.0.0",
+      },
+      integration: {
+        kind: "mcp",
+        displayName: "Fathom",
+        documentationUrl: "https://developers.fathom.ai/mcp-docs",
+        verifiedAt: "2026-09-10",
+        verification: "documentation-only",
+        setup: { mode: "oauth", instructions: "Sign in to Fathom." },
+        logo: "fathom.png",
+      },
+    });
+
+    expect(match).toMatchObject({
+      name: "fathom",
+      path: "local:plugins/mcp-catalog/fathom@1.0.0",
+      integration: { kind: "mcp", logo: "fathom.png" },
+      source: {
+        kind: "local",
+        path: "plugins/mcp-catalog/fathom",
+        version: "1.0.0",
+      },
+    });
+  });
+
   test("projects a root entry onto a github source with a display locator", () => {
     expect(
       marketplaceMatch(

package/src/cli/lib/bundled-plugin-packages.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "packages": {}
+}

package/src/cli/lib/bundled-plugin-packages.ts

@@ -0,0 +1,87 @@
+/**
+ * Materialize reviewed local marketplace packages from the generated bundle.
+ * Package keys come from plugins/marketplace.json and never resolve against a
+ * caller-controlled filesystem root.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import bundledPackages from "./bundled-plugin-packages.json" with { type: "json" };
+
+interface BundledPackageFile {
+  readonly path: string;
+  readonly contentBase64: string;
+}
+
+interface BundledPackage {
+  readonly version: string;
+  readonly files: readonly BundledPackageFile[];
+}
+
+const packages = bundledPackages.packages as Record<string, BundledPackage>;
+
+export class BundledPluginPackageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BundledPluginPackageError";
+  }
+}
+
+/** Return the embedded package when its path and version match the catalog. */
+export function getBundledPluginPackage(
+  path: string,
+  version: string,
+): BundledPackage | null {
+  const pluginPackage = packages[path];
+  return pluginPackage?.version === version ? pluginPackage : null;
+}
+
+/** Read one UTF-8 file from an exact embedded package. */
+export function readBundledPluginFile(
+  path: string,
+  version: string,
+  filePath: string,
+): string | null {
+  const file = getBundledPluginPackage(path, version)?.files.find(
+    (candidate) => candidate.path === filePath,
+  );
+  return file
+    ? Buffer.from(file.contentBase64, "base64").toString("utf8")
+    : null;
+}
+
+/** Copy one exact embedded package into an existing staging directory. */
+export function materializeBundledPluginPackage(
+  path: string,
+  version: string,
+  destination: string,
+): number {
+  const pluginPackage = getBundledPluginPackage(path, version);
+  if (!pluginPackage) {
+    throw new BundledPluginPackageError(
+      `Bundled plugin package ${path} @ ${version} is unavailable`,
+    );
+  }
+
+  for (const file of pluginPackage.files) {
+    if (
+      file.path.length === 0 ||
+      file.path.startsWith("/") ||
+      file.path.includes("\\") ||
+      file.path
+        .split("/")
+        .some(
+          (segment) => segment === "." || segment === ".." || segment === "",
+        )
+    ) {
+      throw new BundledPluginPackageError(
+        `Bundled plugin package ${path} contains an unsafe file path`,
+      );
+    }
+    const target = join(destination, ...file.path.split("/"));
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, Buffer.from(file.contentBase64, "base64"));
+  }
+  return pluginPackage.files.length;
+}

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

@@ -290,7 +290,7 @@ export async function diffPlugin(
 
   const meta = readInstallMeta(target);
   const commit = meta?.commit ?? null;
-  if (!meta || !commit) {
+  if (!meta || meta.source.kind !== "github" || !commit) {
     throw new PluginDiffUnavailableError(
       name,
       `no install commit was recorded (an older or manually-copied install); reinstall with 'assistant plugins install ${name} --force' to record provenance`,