@vellumai/assistant 0.12.3 → 0.12.4-dev.202609231715.8da971c

package/src/cli/commands/plugins.ts

@@ -238,7 +238,15 @@ export function registerPluginsCommand(program: Command): void {
               const platformEnabled =
                 libs.catalogLocal.arePlatformFeaturesEnabled();
               if (platformEnabled) {
+                if (!libs.catalogLocal.isPluginCatalogEntryVisible(nameOrUrl)) {
+                  console.error(
+                    `Plugin "${nameOrUrl}" is not in the marketplace catalog.`,
+                  );
+                  process.exitCode = 1;
+                  return;
+                }
                 let match;
+                let catalogResolved = false;
                 try {
                   match = (
                     await libs.catalogCache.getPluginCatalog(
@@ -246,10 +254,18 @@ export function registerPluginsCommand(program: Command): void {
                       { fetch: globalThis.fetch.bind(globalThis) },
                     )
                   ).matches.find((candidate) => candidate.name === nameOrUrl);
+                  catalogResolved = true;
                 } catch {
                   // The install endpoint remains authoritative and can succeed
                   // independently when catalog discovery is unavailable.
                 }
+                if (!match && catalogResolved) {
+                  console.error(
+                    `Plugin "${nameOrUrl}" is not in the marketplace catalog.`,
+                  );
+                  process.exitCode = 1;
+                  return;
+                }
                 if (match?.source.kind === "local") {
                   result = await libs.installGitHub.installPlugin(
                     {

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

@@ -306,6 +306,35 @@ describe("inspectPlugin", () => {
     expect(result.remote?.commit).toBe(SHA_B);
   });
 
+  test("hides an uninstalled gated integration without fetching the marketplace", async () => {
+    let fetchCalls = 0;
+    const fetch = (async () => {
+      fetchCalls += 1;
+      return new Response("unexpected request", { status: 500 });
+    }) as FetchLike;
+
+    await expect(
+      inspectPlugin(
+        { name: "gamma" },
+        { fetch, workspacePluginsDir: workspace },
+      ),
+    ).rejects.toBeInstanceOf(PluginInspectNotFoundError);
+    expect(fetchCalls).toBe(0);
+  });
+
+  test("keeps an installed gated integration inspectable", async () => {
+    installPlugin(workspace, "gamma", { sidecar: null });
+    const fetch = makeFetch({ marketplace: manifestWith("gamma", SHA_B) });
+
+    const result = await inspectPlugin(
+      { name: "gamma" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    expect(result.installed).toBe(true);
+    expect(result.local?.description).toBe("Installed copy.");
+  });
+
   test("previews an uninstalled bundled provider offline without fetching GitHub", async () => {
     const savedDisablePlatform = process.env.VELLUM_DISABLE_PLATFORM;
     const savedIsPlatform = process.env.IS_PLATFORM;

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

@@ -19,6 +19,7 @@ import {
 import type { FetchLike } from "../fetch-like.js";
 import {
   getPluginCatalog,
+  getPluginCatalogForInstalledMetadata,
   invalidatePluginCatalogCache,
   mergePlatformCatalogWithBundledLocals,
   PLUGIN_CATALOG_CACHE_TTL_MS,
@@ -102,7 +103,7 @@ describe("getPluginCatalog", () => {
 
     // THEN the platform is fetched exactly once — the second call is cached
     expect(calls()).toBe(1);
-    expect(first).toBe(second);
+    expect(first).toEqual(second);
     expect(githubNames(first)).toEqual(["a"]);
     expect(first.ref).toBe("main");
   });
@@ -161,7 +162,10 @@ describe("getPluginCatalog", () => {
     delete process.env.IS_PLATFORM;
 
     const { fetch, calls } = platformFetch(["ignored"]);
-    const deps: SearchPluginsDeps = { fetch };
+    const deps: SearchPluginsDeps = {
+      fetch,
+      featureFlagEnabled: () => true,
+    };
 
     // WHEN we request the catalog
     const result = await getPluginCatalog("main", deps);
@@ -173,6 +177,32 @@ describe("getPluginCatalog", () => {
     // The requested ref is echoed onto the wire contract.
     expect(result.ref).toBe("main");
   });
+
+  test("applies feature-flag visibility to bundled catalog entries", async () => {
+    process.env.VELLUM_DISABLE_PLATFORM = "true";
+    delete process.env.IS_PLATFORM;
+
+    const { fetch } = platformFetch(["ignored"]);
+    const result = await getPluginCatalog("main", {
+      fetch,
+      featureFlagEnabled: () => false,
+    });
+
+    expect(result.matches.map((match) => match.name)).not.toContain("gamma");
+    expect(result.matches.map((match) => match.name)).toContain("fathom");
+  });
+
+  test("preserves hidden entries for installed-plugin metadata", async () => {
+    process.env.VELLUM_DISABLE_PLATFORM = "true";
+    delete process.env.IS_PLATFORM;
+
+    const { fetch } = platformFetch(["ignored"]);
+    const result = await getPluginCatalogForInstalledMetadata("main", {
+      fetch,
+    });
+
+    expect(result.matches.map((match) => match.name)).toContain("gamma");
+  });
 });
 
 describe("mergePlatformCatalogWithBundledLocals", () => {
@@ -228,4 +258,64 @@ describe("mergePlatformCatalogWithBundledLocals", () => {
     expect(merged.matches[1]?.source.kind).toBe("local");
     expect(merged.ref).toBe("main");
   });
+  test("keeps the bundled integration when a platform row without one shadows it", () => {
+    const integration = {
+      kind: "mcp",
+      displayName: "Fathom",
+      documentationUrl: "https://example.com/docs",
+      verifiedAt: "2026-09-10",
+      verification: "documentation-only",
+      setup: { mode: "oauth", instructions: "Sign in." },
+      logo: "fathom.png",
+    } as const;
+    const platformIntegration = { ...integration, displayName: "Platform" };
+    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),
+          },
+        },
+        {
+          name: "linear",
+          path: "github:provider/linear@pin",
+          category: null,
+          integration: platformIntegration,
+          source: {
+            kind: "github",
+            repo: "provider/linear",
+            ref: "0".repeat(40),
+          },
+        },
+      ],
+    };
+    const bundled: PluginCatalog = {
+      ref: "bundled",
+      matches: ["fathom", "linear"].map((name) => ({
+        name,
+        path: `local:plugins/mcp-catalog/${name}@1.0.0`,
+        category: null,
+        integration,
+        source: {
+          kind: "local",
+          path: `plugins/mcp-catalog/${name}`,
+          version: "1.0.0",
+        },
+      })),
+    };
+
+    const merged = mergePlatformCatalogWithBundledLocals(platform, bundled);
+
+    const [fathom, linear] = merged.matches;
+    expect(fathom?.source.kind).toBe("github");
+    expect(fathom?.integration).toEqual(integration);
+    expect(linear?.source.kind).toBe("github");
+    expect(linear?.integration).toEqual(platformIntegration);
+  });
 });

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

@@ -13,6 +13,7 @@ import bundledManifest from "../bundled-marketplace.json" with { type: "json" };
 import {
   buildBundledPluginCatalog,
   readBundledPluginCatalog,
+  resolveBundledPluginSource,
 } from "../plugin-catalog-local.js";
 import { marketplaceManifestSchema } from "../plugin-marketplace.js";
 import { marketplaceMatch } from "../search-plugins.js";
@@ -96,3 +97,17 @@ describe("readBundledPluginCatalog", () => {
     expect(readBundledPluginCatalog()).toBe(readBundledPluginCatalog());
   });
 });
+
+describe("resolveBundledPluginSource", () => {
+  test("hides a QA integration while its feature flag is off", () => {
+    expect(resolveBundledPluginSource("gamma", () => false)).toBeNull();
+  });
+
+  test("resolves a QA integration while its feature flag is on", () => {
+    expect(resolveBundledPluginSource("gamma", () => true)).toEqual({
+      kind: "local",
+      path: "plugins/mcp-catalog/gamma",
+      version: "1.0.2",
+    });
+  });
+});

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

@@ -161,14 +161,78 @@ describe("fetchPluginCatalogFromPlatform", () => {
     await expect(promise).rejects.toMatchObject({ status: 502 });
   });
 
-  test("throws on a schema violation", async () => {
+  test.each([
+    ["a missing plugins array", {}],
+    ["a non-array plugins field", { plugins: "nope" }],
+    ["a non-object body", []],
+  ])("throws on an invalid envelope (%s)", async (_label, body) => {
     const promise = fetchPluginCatalogFromPlatform({
-      fetch: platformFetch({ plugins: [{ repo: "acme/x", ref: SHA_A }] }),
+      fetch: platformFetch(body),
     });
     await expect(promise).rejects.toBeInstanceOf(PluginCatalogUnavailableError);
     await expect(promise).rejects.toMatchObject({ status: 502 });
   });
 
+  test("skips rows that fail the base row schema and keeps the rest", async () => {
+    const catalog = await fetchPluginCatalogFromPlatform({
+      fetch: platformFetch({
+        plugins: [
+          { repo: "acme/nameless", ref: SHA_A },
+          { name: 42, repo: "acme/numeric", ref: SHA_A },
+          "not-a-row",
+          { name: "good", repo: "acme/good", ref: SHA_B },
+        ],
+      }),
+    });
+    expect(catalog.matches.map((m) => m.name)).toEqual(["good"]);
+  });
+
+  test("keeps a row whose integration is invalid, without the integration", async () => {
+    const catalog = await fetchPluginCatalogFromPlatform({
+      fetch: platformFetch({
+        plugins: [
+          {
+            name: "snake-case",
+            repo: "acme/snake-case",
+            ref: SHA_A,
+            description: "kept",
+            integration: {
+              kind: "mcp",
+              display_name: "Snake Case",
+              documentation_url: "https://example.com/docs",
+              verified_at: "2026-09-10",
+              verification: "documentation-only",
+              setup: { mode: "oauth", instructions: "Sign in." },
+              logo: "snake-case.png",
+            },
+          },
+          {
+            name: "valid",
+            repo: "acme/valid",
+            ref: SHA_B,
+            integration: {
+              kind: "mcp",
+              displayName: "Valid",
+              documentationUrl: "https://example.com/docs",
+              verifiedAt: "2026-09-10",
+              verification: "documentation-only",
+              setup: { mode: "manual", instructions: "Paste a key." },
+              logo: "valid.png",
+            },
+          },
+        ],
+      }),
+    });
+
+    expect(catalog.matches.map((m) => m.name)).toEqual(["snake-case", "valid"]);
+    expect(catalog.matches[0]).toMatchObject({
+      name: "snake-case",
+      description: "kept",
+    });
+    expect(catalog.matches[0]?.integration).toBeUndefined();
+    expect(catalog.matches[1]?.integration?.displayName).toBe("Valid");
+  });
+
   test("throws when fetch rejects (network error / abort)", async () => {
     const promise = fetchPluginCatalogFromPlatform({
       fetch: (async () => {

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

@@ -195,6 +195,27 @@ describe("catalog-backed resolvers (bundled, offline)", () => {
       await resolvePluginSourceFromCatalog("no-such-plugin", rejectingDeps),
     ).toBeNull();
   });
+
+  test("does not resolve a QA integration while its feature flag is off", async () => {
+    expect(
+      await resolvePluginSourceFromCatalog("gamma", {
+        ...rejectingDeps,
+        featureFlagEnabled: () => false,
+      }),
+    ).toBeNull();
+  });
+
+  test("resolves a QA integration while its feature flag is on", async () => {
+    expect(
+      await resolvePluginSourceFromCatalog("gamma", {
+        ...rejectingDeps,
+        featureFlagEnabled: () => true,
+      }),
+    ).toMatchObject({
+      kind: "local",
+      path: "plugins/mcp-catalog/gamma",
+    });
+  });
 });
 
 describe("catalog-backed resolvers (platform enabled)", () => {

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

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  filterPluginCatalogByFeatureFlags,
+  MCP_CATALOG_QA_INTEGRATIONS_FLAG,
+} from "../plugin-catalog-visibility.js";
+import type { PluginCatalog, PluginSearchMatch } from "../search-plugins.js";
+
+function match(name: string): PluginSearchMatch {
+  return {
+    name,
+    path: `local:plugins/mcp-catalog/${name}@1.0.0`,
+    category: null,
+    source: {
+      kind: "local",
+      path: `plugins/mcp-catalog/${name}`,
+      version: "1.0.0",
+    },
+  };
+}
+
+function catalog(names: string[]): PluginCatalog {
+  return { ref: "main", matches: names.map(match) };
+}
+
+describe("filterPluginCatalogByFeatureFlags", () => {
+  test("hides QA integrations while the flag is off", () => {
+    const input = catalog([
+      "fathom",
+      "gamma",
+      "guru",
+      "intercom",
+      "ramp",
+      "semrush",
+      "typeform",
+      "notion",
+    ]);
+
+    const result = filterPluginCatalogByFeatureFlags(input, (key) => {
+      expect(key).toBe(MCP_CATALOG_QA_INTEGRATIONS_FLAG);
+      return false;
+    });
+
+    expect(result.matches.map((entry) => entry.name)).toEqual([
+      "fathom",
+      "notion",
+    ]);
+  });
+
+  test("returns the full catalog while the flag is on", () => {
+    const input = catalog([
+      "fathom",
+      "gamma",
+      "guru",
+      "intercom",
+      "ramp",
+      "semrush",
+      "typeform",
+    ]);
+
+    const result = filterPluginCatalogByFeatureFlags(input, () => true);
+
+    expect(result).toBe(input);
+  });
+});

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

@@ -513,6 +513,49 @@ describe("getPluginDetails (bundled catalog, offline)", () => {
     expect(details.ref).toBe(historicalRef);
   });
 
+  test("hides a gated integration at an explicit historical ref", async () => {
+    const historicalRef = "a".repeat(40);
+    let fetchCalls = 0;
+    const fetch = (async () => {
+      fetchCalls += 1;
+      return new Response("unexpected request", { status: 500 });
+    }) as FetchLike;
+
+    await expect(
+      getPluginDetails(
+        { name: "gamma", ref: historicalRef },
+        { fetch, workspacePluginsDir: workspace },
+      ),
+    ).rejects.toBeInstanceOf(PluginDetailsNotFoundError);
+    expect(fetchCalls).toBe(0);
+  });
+
+  test("keeps an installed gated integration visible at an explicit historical ref", async () => {
+    const target = join(workspace, "gamma");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "README.md"), "# Installed Gamma");
+    writeFileSync(
+      join(target, "package.json"),
+      JSON.stringify({ version: "1.0.0", description: "local gamma" }),
+    );
+    let fetchCalls = 0;
+    const fetch = (async () => {
+      fetchCalls += 1;
+      return new Response("unexpected request", { status: 500 });
+    }) as FetchLike;
+
+    const details = await getPluginDetails(
+      { name: "gamma", ref: "a".repeat(40) },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    expect(details.installed).toBe(true);
+    expect(details.readme).toBe("# Installed Gamma");
+    expect(details.description).toBe("local gamma");
+    expect(details.source).toBeNull();
+    expect(fetchCalls).toBe(0);
+  });
+
   test("degrades gracefully when the historical marketplace fetch fails", async () => {
     // GIVEN an installed copy and a historical ref whose marketplace fetch errors
     const historicalRef = "a".repeat(40);

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

@@ -172,6 +172,17 @@ describe("plugins install by name — disable-platform mode", () => {
     expect(message).toContain("not in the bundled marketplace catalog");
   });
 
+  test("does not install a feature-gated bundled integration", async () => {
+    process.env.VELLUM_DISABLE_PLATFORM = "true";
+    delete process.env.IS_PLATFORM;
+
+    await runInstall("gamma");
+
+    expect(installPluginCalls).toHaveLength(0);
+    expect(platformInstallCalls).toHaveLength(0);
+    expect(process.exitCode).toBe(1);
+  });
+
   test("uses the platform install endpoint when platform features are enabled", async () => {
     delete process.env.VELLUM_DISABLE_PLATFORM;
     delete process.env.IS_PLATFORM;
@@ -184,6 +195,21 @@ describe("plugins install by name — disable-platform mode", () => {
     expect(process.exitCode).not.toBe(1);
   });
 
+  test("does not install a name absent from a successful platform catalog", async () => {
+    delete process.env.VELLUM_DISABLE_PLATFORM;
+    delete process.env.IS_PLATFORM;
+    const errSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    await runInstall("gamma");
+
+    expect(installPluginCalls).toHaveLength(0);
+    expect(platformInstallCalls).toHaveLength(0);
+    expect(process.exitCode).toBe(1);
+    expect(String(errSpy.mock.calls[0]?.[0])).toContain(
+      "not in the marketplace catalog",
+    );
+  });
+
   test("installs a platform-visible local package without the platform tar endpoint", async () => {
     delete process.env.VELLUM_DISABLE_PLATFORM;
     delete process.env.IS_PLATFORM;

package/src/cli/lib/bundled-marketplace.json

@@ -176,16 +176,16 @@
       "icon": "\ud83d\udcbb"
     },
     {
-      "name": "ecommerce-wismo-supporter",
+      "name": "ecommerce-order-supporter",
       "description": "Resolves ecommerce Where-Is-My-Order (WISMO) support inquiries, cross-checks real-time carrier tracking milestones, flags delivery exceptions, and stages customer update drafts without helpdesk seat taxes.",
       "category": "commerce",
       "icon": "📦",
       "license": "MIT",
-      "homepage": "https://github.com/ZeebBoyBlue/ecommerce-wismo-supporter",
+      "homepage": "https://github.com/ZeebBoyBlue/ecommerce-order-supporter",
       "source": {
         "source": "github",
-        "repo": "ZeebBoyBlue/ecommerce-wismo-supporter",
-        "ref": "9218c23d325c749500d59b6ae651f38264a43cd1"
+        "repo": "ZeebBoyBlue/ecommerce-order-supporter",
+        "ref": "35e2165a14447a897aee750a198c3f166458226b"
       }
     },
     {

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

@@ -31,6 +31,7 @@ import {
   arePlatformFeaturesEnabled,
   readBundledLocalPluginCatalog,
 } from "./plugin-catalog-local.js";
+import { isPluginCatalogEntryVisible } from "./plugin-catalog-visibility.js";
 import { DEFAULT_PLUGIN_REF } from "./plugin-constants.js";
 import {
   compareFingerprint,
@@ -338,6 +339,10 @@ export async function inspectPlugin(
   const local = entry ? readLocal(entry, readInstallMeta(entry.target)) : null;
   const surfaces = entry ? detectPluginSurfaces(entry.target) : null;
 
+  if (!installed && !isPluginCatalogEntryVisible(name)) {
+    throw new PluginInspectNotFoundError(name);
+  }
+
   let remote: PluginRemoteInfo | null = null;
   let remoteError: string | null = null;
   const installedLocalSource = local?.source?.kind === "local";

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

@@ -14,6 +14,7 @@ import {
   readBundledPluginCatalog,
 } from "./plugin-catalog-local.js";
 import { fetchPluginCatalogFromPlatform } from "./plugin-catalog-platform.js";
+import { filterPluginCatalogByFeatureFlags } from "./plugin-catalog-visibility.js";
 import type { PluginCatalog, SearchPluginsDeps } from "./search-plugins.js";
 
 /** How long a fetched catalog is served before a refresh is attempted. */
@@ -24,18 +25,35 @@ interface CacheEntry {
   timestamp: number;
 }
 
+type PluginCatalogLoadDeps = Pick<SearchPluginsDeps, "fetch">;
+
 const cache = new Map<string, CacheEntry>();
 
-/** Add bundled local packages without overriding platform-authoritative rows. */
+/**
+ * Add bundled local packages without overriding platform-authoritative rows.
+ * A platform row without an integration borrows the bundled row's
+ * integration of the same name, so an integration the platform omits or
+ * serves malformed never disappears from the catalog.
+ */
 export function mergePlatformCatalogWithBundledLocals(
   platform: PluginCatalog,
   bundledLocal: PluginCatalog = readBundledLocalPluginCatalog(),
 ): PluginCatalog {
+  const bundledByName = new Map(
+    bundledLocal.matches.map((match) => [match.name, match]),
+  );
+  const platformMatches = platform.matches.map((match) => {
+    const bundledIntegration = bundledByName.get(match.name)?.integration;
+    if (match.integration || !bundledIntegration) {
+      return match;
+    }
+    return { ...match, integration: bundledIntegration };
+  });
   const seen = new Set(platform.matches.map((match) => match.name));
   return {
     ref: platform.ref,
     matches: [
-      ...platform.matches,
+      ...platformMatches,
       ...bundledLocal.matches.filter((match) => !seen.has(match.name)),
     ].sort((a, b) => a.name.localeCompare(b.name)),
   };
@@ -50,9 +68,9 @@ export function mergePlatformCatalogWithBundledLocals(
  * fetch failure propagates so the caller can surface it (e.g. map a rate-limit
  * to 503) — no stale catalog is ever served.
  */
-export async function getPluginCatalog(
+async function loadPluginCatalog(
   ref: string,
-  deps: SearchPluginsDeps,
+  deps: PluginCatalogLoadDeps,
 ): Promise<PluginCatalog> {
   if (!arePlatformFeaturesEnabled()) {
     return { ...readBundledPluginCatalog(), ref };
@@ -69,6 +87,25 @@ export async function getPluginCatalog(
   return merged;
 }
 
+/** Installable catalog with feature-flag visibility applied. */
+export async function getPluginCatalog(
+  ref: string,
+  deps: SearchPluginsDeps,
+): Promise<PluginCatalog> {
+  return filterPluginCatalogByFeatureFlags(
+    await loadPluginCatalog(ref, deps),
+    deps.featureFlagEnabled,
+  );
+}
+
+/** Category metadata for plugins already installed, including hidden entries. */
+export async function getPluginCatalogForInstalledMetadata(
+  ref: string,
+  deps: PluginCatalogLoadDeps,
+): Promise<PluginCatalog> {
+  return loadPluginCatalog(ref, deps);
+}
+
 /** Invalidate the cache (for testing or forced refresh). */
 export function invalidatePluginCatalogCache(): void {
   cache.clear();

package/src/cli/lib/plugin-catalog-local.ts

@@ -13,6 +13,10 @@
  */
 
 import bundledManifest from "./bundled-marketplace.json" with { type: "json" };
+import {
+  isPluginCatalogEntryVisible,
+  type PluginCatalogFeatureFlagResolver,
+} from "./plugin-catalog-visibility.js";
 import {
   type MarketplaceEntry,
   marketplaceManifestSchema,
@@ -27,6 +31,7 @@ import {
 // Re-exported so `local`-tagged CLI commands can gate on platform features
 // without importing `platform/` directly (cli/no-daemon-internals allows lib).
 export { arePlatformFeaturesEnabled } from "../../platform/feature-gate.js";
+export { isPluginCatalogEntryVisible };
 
 let memoizedEntries: readonly MarketplaceEntry[] | undefined;
 
@@ -80,6 +85,10 @@ export function readBundledLocalPluginCatalog(): PluginCatalog {
  */
 export function resolveBundledPluginSource(
   name: string,
+  isFeatureFlagEnabled?: PluginCatalogFeatureFlagResolver,
 ): ResolvedPluginSource | null {
+  if (!isPluginCatalogEntryVisible(name, isFeatureFlagEnabled)) {
+    return null;
+  }
   return resolveMarketplaceSource(name, bundledEntries());
 }