@vellumai/assistant 0.8.8 → 0.8.9-staging.2

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

@@ -1,9 +1,14 @@
 /**
  * Tests for {@link installPlugin}.
  *
- * Network is replaced with an in-memory fixture passed via the `fetch`
- * dependency — no globals are monkey-patched and no `--test-hook` exports
- * leak into production code.
+ * Two materialization paths are exercised without touching the network or
+ * spawning real subprocesses:
+ *   - First-party plugins are fetched from the GitHub Contents API, replaced
+ *     by an in-memory fixture passed via the `fetch` dependency.
+ *   - External (whitelisted) plugins are shallow-cloned with `git`, replaced
+ *     by a fake {@link GitRunner} that materializes a tree into the clone dir.
+ * No globals are monkey-patched and no `--test-hook` exports leak into
+ * production code.
  */
 
 import {
@@ -16,92 +21,84 @@ import {
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import {
   type FetchLike,
+  type GitRunner,
   installPlugin,
   InvalidPluginNameError,
   PluginAlreadyInstalledError,
   PluginNotFoundError,
+  PluginSourceUnavailableError,
   sanitizePluginName,
 } from "../install-from-github.js";
 
+const CANON_REPO = "vellum-ai/vellum-assistant";
+/** Synthetic host the fixtures use for Contents API `download_url`s. */
+const DOWNLOAD_HOST = "https://files.test/";
+
 /**
- * Build a GitHub Contents API fixture from an in-memory file tree.
+ * Build a `fetch` that serves the GitHub Contents API from an in-memory tree.
  *
- * `tree` maps a path under the canonical prefix (e.g. `simple-memory`,
- * `simple-memory/hooks/init.ts`) to either:
- *   - a `Uint8Array`/`string` → a file with that content
- *   - `null` → a directory
+ * `tree` is keyed by full canonical-repo path (e.g.
+ * `experimental/plugins/simple-memory/package.json`) and maps each entry to a
+ * file's content (`string`/`Uint8Array`) or `null` for an explicit directory.
+ * Directory listings are derived from the key set; file `download_url`s point
+ * at {@link DOWNLOAD_HOST} and are served with the stored bytes.
  *
- * The fixture answers GET requests against
- *  - `https://api.github.com/repos/vellum-ai/vellum-assistant/contents/...`
- *  - any other URL we hand out as `download_url`
+ * The marketplace manifest lookup is answered with `manifest` (or a 404 when
+ * omitted, so resolution degrades to the first-party source).
  */
-function fixtureFetch(
-  tree: Record<string, Uint8Array | string | null>,
-): FetchLike {
-  const PREFIX_API =
-    "https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins/";
-  const PREFIX_RAW =
-    "https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/experimental/plugins/";
-
-  function listing(apiPath: string): unknown {
-    const rel = apiPath.startsWith("experimental/plugins/")
-      ? apiPath.slice("experimental/plugins/".length)
-      : apiPath;
-    const prefix = rel ? rel + "/" : "";
-    const direct = new Map<string, "file" | "dir">();
+function makeContentsFetch(opts: {
+  tree: Record<string, Uint8Array | string | null>;
+  manifest?: unknown;
+}): FetchLike {
+  const MANIFEST_URL = `https://api.github.com/repos/${CANON_REPO}/contents/experimental/plugins/marketplace.json`;
+  const CONTENTS = `https://api.github.com/repos/${CANON_REPO}/contents/`;
+  const { tree } = opts;
+
+  function listing(apiPath: string):
+    | {
+        name: string;
+        path: string;
+        type: string;
+        download_url: string | null;
+      }[]
+    | null {
+    const prefix = apiPath ? `${apiPath}/` : "";
+    const direct = new Map<string, boolean>();
     for (const key of Object.keys(tree)) {
       if (!key.startsWith(prefix)) continue;
       const remainder = key.slice(prefix.length);
       if (!remainder) continue;
-      const [head, ...rest] = remainder.split("/");
-      if (rest.length === 0) {
-        const isDir = tree[key] === null;
-        if (!direct.has(head!)) direct.set(head!, isDir ? "dir" : "file");
-      } else {
-        if (!direct.has(head!)) direct.set(head!, "dir");
-      }
+      const seg = remainder.split("/")[0]!;
+      const isDir = remainder.includes("/") || tree[`${prefix}${seg}`] === null;
+      direct.set(seg, (direct.get(seg) ?? false) || isDir);
     }
     if (direct.size === 0) return null;
-    return Array.from(direct.entries()).map(([name, type]) => ({
-      name,
-      // GitHub returns `path` rooted at the repo, not relative to the queried
-      // directory — mirror that so the recursive copy hits the same fixture
-      // handler on the way down.
-      path: `experimental/plugins/${prefix}${name}`,
-      type,
-      size: type === "file" ? (tree[`${prefix}${name}`] as string).length : 0,
-      download_url:
-        type === "file" ? `${PREFIX_RAW}${prefix}${name}` : null,
-    }));
+    return Array.from(direct.entries()).map(([name, isDir]) => {
+      const path = `${prefix}${name}`;
+      return isDir
+        ? { name, path, type: "dir", download_url: null }
+        : { name, path, type: "file", download_url: `${DOWNLOAD_HOST}${path}` };
+    });
   }
 
-  return (async (input: RequestInfo | URL, _init?: RequestInit) => {
+  return (async (input: RequestInfo | URL) => {
     const url = typeof input === "string" ? input : input.toString();
 
-    if (url.startsWith(PREFIX_API)) {
-      const after = url.slice(PREFIX_API.length).split("?")[0]!;
-      const apiPath = `experimental/plugins/${decodeURIComponent(after)}`;
-      const body = listing(apiPath);
-      if (body === null) {
+    if (url.startsWith(MANIFEST_URL)) {
+      if (opts.manifest === undefined) {
         return new Response("not found", { status: 404 });
       }
-      return new Response(JSON.stringify(body), {
-        status: 200,
-        headers: { "content-type": "application/json" },
-      });
+      return new Response(JSON.stringify(opts.manifest), { status: 200 });
     }
 
-    if (url.startsWith(PREFIX_RAW)) {
-      const key =
-        "experimental/plugins/" +
-        decodeURIComponent(url.slice(PREFIX_RAW.length));
-      const rel = key.slice("experimental/plugins/".length);
-      const file = tree[rel];
+    if (url.startsWith(DOWNLOAD_HOST)) {
+      const path = decodeURIComponent(url.slice(DOWNLOAD_HOST.length));
+      const file = tree[path];
       if (file === null || file === undefined) {
         return new Response("not found", { status: 404 });
       }
@@ -110,11 +107,82 @@ function fixtureFetch(
       return new Response(Buffer.from(bytes), { status: 200 });
     }
 
-    return new Response("unexpected url: " + url, { status: 500 });
+    if (url.startsWith(CONTENTS)) {
+      const after = decodeURIComponent(
+        url.slice(CONTENTS.length).split("?")[0]!,
+      );
+      const body = listing(after);
+      if (body === null) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(JSON.stringify(body), { status: 200 });
+    }
+
+    return new Response(`unexpected url: ${url}`, { status: 500 });
   }) as FetchLike;
 }
 
-describe("installPlugin", () => {
+/** First-party fixture: keys are relative to `experimental/plugins/`. */
+function fixtureFetch(
+  tree: Record<string, Uint8Array | string | null>,
+): FetchLike {
+  const full: Record<string, Uint8Array | string | null> = {};
+  for (const [key, value] of Object.entries(tree)) {
+    full[`experimental/plugins/${key}`] = value;
+  }
+  return makeContentsFetch({ tree: full });
+}
+
+/**
+ * Build a fake {@link GitRunner} that simulates a shallow clone.
+ *
+ * On `fetch`, the configured `tree` (repo-relative path → content, `null` =
+ * directory) plus a token `.git/config` are written into the clone `cwd`, so
+ * the subsequent copy can be asserted to include the tree and exclude `.git`.
+ * `rev-parse HEAD` returns `commit`. Optional hooks let a test record the git
+ * arguments or inject a fetch failure.
+ */
+function fakeGitRunner(opts: {
+  tree: Record<string, string | null>;
+  commit?: string;
+  calls?: string[][];
+  fetchError?: Error;
+}): GitRunner {
+  const commit = opts.commit ?? "abc123def4567890abc123def4567890abcdef12";
+  return async (args, { cwd }) => {
+    opts.calls?.push([...args]);
+    switch (args[0]) {
+      case "fetch": {
+        if (opts.fetchError) throw opts.fetchError;
+        mkdirSync(join(cwd, ".git"), { recursive: true });
+        writeFileSync(join(cwd, ".git", "config"), "[core]\n");
+        for (const [rel, content] of Object.entries(opts.tree)) {
+          if (content === null) {
+            mkdirSync(join(cwd, rel), { recursive: true });
+            continue;
+          }
+          const dest = join(cwd, rel);
+          mkdirSync(dirname(dest), { recursive: true });
+          writeFileSync(dest, content);
+        }
+        return { stdout: "" };
+      }
+      case "rev-parse":
+        return { stdout: `${commit}\n` };
+      default:
+        return { stdout: "" };
+    }
+  };
+}
+
+/** A git runner that fails the test if any git command is invoked. */
+const unusedGitRunner: GitRunner = async (args) => {
+  throw new Error(
+    `git should not run for a first-party install: ${args.join(" ")}`,
+  );
+};
+
+describe("installPlugin — first-party", () => {
   let ws: string;
   let pluginsDir: string;
 
@@ -128,7 +196,7 @@ describe("installPlugin", () => {
     rmSync(ws, { recursive: true, force: true });
   });
 
-  test("copies the GitHub tree into <workspacePluginsDir>/<name>", async () => {
+  test("copies a first-party plugin into <workspacePluginsDir>/<name>", async () => {
     const result = await installPlugin(
       { name: "simple-memory", force: false, ref: "main" },
       {
@@ -149,6 +217,8 @@ describe("installPlugin", () => {
     expect(result.target).toBe(target);
     expect(result.fileCount).toBe(4);
     expect(result.ref).toBe("main");
+    // First-party installs have no clone, so no commit is resolved.
+    expect(result.commit).toBeNull();
     expect(existsSync(join(target, "package.json"))).toBe(true);
     expect(existsSync(join(target, "README.md"))).toBe(true);
     expect(existsSync(join(target, "hooks", "init.ts"))).toBe(true);
@@ -158,6 +228,33 @@ describe("installPlugin", () => {
     );
   });
 
+  test("writes a provenance manifest recording the source and ref", async () => {
+    // GIVEN a first-party install
+    const target = join(pluginsDir, "simple-memory");
+
+    // WHEN it completes
+    await installPlugin(
+      { name: "simple-memory", force: false, ref: "main" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory/package.json": '{"name":"simple-memory"}',
+        }),
+        workspacePluginsDir: pluginsDir,
+      },
+    );
+
+    // THEN a hidden manifest records the resolved coordinates (no commit for
+    // first-party) and is not counted as a plugin file
+    const manifest = JSON.parse(
+      readFileSync(join(target, ".vellum-plugin.json"), "utf-8"),
+    );
+    expect(manifest.name).toBe("simple-memory");
+    expect(manifest.source.kind).toBe("first-party");
+    expect(manifest.source.repo).toBe("vellum-assistant");
+    expect(manifest.source.ref).toBe("main");
+    expect(manifest.commit).toBeUndefined();
+  });
+
   test("refuses to overwrite an existing install without --force", async () => {
     const target = join(pluginsDir, "simple-memory");
     mkdirSync(target, { recursive: true });
@@ -168,7 +265,6 @@ describe("installPlugin", () => {
         { name: "simple-memory", force: false, ref: "main" },
         {
           fetch: fixtureFetch({
-            "simple-memory": null,
             "simple-memory/package.json": "{}",
           }),
           workspacePluginsDir: pluginsDir,
@@ -189,7 +285,6 @@ describe("installPlugin", () => {
       { name: "simple-memory", force: true, ref: "main" },
       {
         fetch: fixtureFetch({
-          "simple-memory": null,
           "simple-memory/package.json": '{"name":"simple-memory"}',
         }),
         workspacePluginsDir: pluginsDir,
@@ -201,9 +296,9 @@ describe("installPlugin", () => {
   });
 
   test("--force preserves the existing install when the fetch fails", async () => {
-    // Codex P1 from PR-5 review: a transient 5xx during a forced re-install
-    // must NOT delete the previously working plugin. The fetch error
-    // surfaces, but the existing tree on disk is untouched.
+    // A transient 5xx during a forced re-install must NOT delete the
+    // previously working plugin. The fetch error surfaces, but the existing
+    // tree on disk is untouched (all writes go through the staging dir).
     const target = join(pluginsDir, "simple-memory");
     mkdirSync(target, { recursive: true });
     writeFileSync(join(target, "marker"), "pre-existing");
@@ -219,12 +314,9 @@ describe("installPlugin", () => {
       ),
     ).rejects.toThrow(/HTTP 503/);
 
-    // Marker is still there because the failed install never touched the
-    // target — the staging dir handles all writes until the swap.
     expect(readFileSync(join(target, "marker"), "utf-8")).toBe("pre-existing");
     // And no staging dir leaks into the plugins directory.
-    const remaining = readdirSync(pluginsDir);
-    expect(remaining).toEqual(["simple-memory"]);
+    expect(readdirSync(pluginsDir)).toEqual(["simple-memory"]);
   });
 
   test("404 on the canonical path is reported as not-found", async () => {
@@ -259,63 +351,109 @@ describe("installPlugin", () => {
     expect(readdirSync(pluginsDir)).toEqual([]);
   });
 
-  test("respects ref by forwarding to GitHub", async () => {
-    let seenRef: string | undefined;
+  test("a rate-limited contents listing surfaces a retryable PluginSourceUnavailableError", async () => {
+    // GIVEN GitHub's unauthenticated rate limit is exhausted: the contents
+    // listing 403s with the remaining-quota header at zero
+    const rateLimited: FetchLike = (async (input: RequestInfo | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("marketplace.json")) {
+        return new Response("not found", { status: 404 });
+      }
+      if (url.includes("/contents/")) {
+        return new Response("rate limited", {
+          status: 403,
+          headers: { "x-ratelimit-remaining": "0" },
+        });
+      }
+      return new Response("not found", { status: 404 });
+    }) as FetchLike;
+
+    // WHEN we install
+    // THEN the failure is classified as transient (retryable), not a hard
+    // error, so the route can surface a 503 instead of a 500
+    await expect(
+      installPlugin(
+        { name: "demo", force: false, ref: "main" },
+        { fetch: rateLimited, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginSourceUnavailableError);
+
+    // AND no staging dir leaks behind on the transient failure.
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("a forbidden contents listing with quota remaining stays a hard error", async () => {
+    // GIVEN a 403 that is NOT a rate-limit (quota header present and nonzero):
+    // a genuine authorization failure, not a transient one
+    const forbidden: FetchLike = (async (input: RequestInfo | URL) => {
+      const url = typeof input === "string" ? input : input.toString();
+      if (url.includes("marketplace.json")) {
+        return new Response("not found", { status: 404 });
+      }
+      if (url.includes("/contents/")) {
+        return new Response("forbidden", {
+          status: 403,
+          headers: { "x-ratelimit-remaining": "57" },
+        });
+      }
+      return new Response("not found", { status: 404 });
+    }) as FetchLike;
+
+    // WHEN we install
+    // THEN it surfaces as a hard error — NOT the retryable variant — so the
+    // route maps it to 500 rather than inviting an endless retry loop
+    await expect(
+      installPlugin(
+        { name: "demo", force: false, ref: "main" },
+        { fetch: forbidden, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.not.toBeInstanceOf(PluginSourceUnavailableError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("respects ref by forwarding it to the contents listing", async () => {
+    // The requested ref must reach the first-party contents listing request.
+    let listRef: string | undefined;
+    const base = fixtureFetch({ "demo/package.json": "{}" });
+    const fetch: FetchLike = async (input, init) => {
+      const url = typeof input === "string" ? input : input.toString();
+      const match = /\/contents\/experimental\/plugins\/demo\?ref=([^&]+)/.exec(
+        url,
+      );
+      if (match) listRef = decodeURIComponent(match[1]!);
+      return base(url, init);
+    };
+
     await installPlugin(
       { name: "demo", force: false, ref: "feat-branch" },
-      {
-        fetch: (async (input: RequestInfo | URL) => {
-          const url = typeof input === "string" ? input : input.toString();
-          if (url.includes("api.github.com")) {
-            const m = /[?&]ref=([^&]+)/.exec(url);
-            seenRef = m ? decodeURIComponent(m[1]!) : undefined;
-            return new Response(
-              JSON.stringify([
-                {
-                  name: "package.json",
-                  path: "experimental/plugins/demo/package.json",
-                  type: "file",
-                  size: 2,
-                  download_url:
-                    "https://raw.githubusercontent.com/vellum-ai/vellum-assistant/feat-branch/experimental/plugins/demo/package.json",
-                },
-              ]),
-              {
-                status: 200,
-                headers: { "content-type": "application/json" },
-              },
-            );
-          }
-          return new Response("{}", { status: 200 });
-        }) as FetchLike,
-        workspacePluginsDir: pluginsDir,
-      },
+      { fetch, workspacePluginsDir: pluginsDir },
     );
 
-    expect(seenRef).toBe("feat-branch");
+    expect(listRef).toBe("feat-branch");
     expect(existsSync(join(pluginsDir, "demo", "package.json"))).toBe(true);
   });
 
   test("rejects untrusted entry names from the GitHub response", async () => {
-    // Devin P2 from PR-5 review: even though GitHub returns trustworthy data,
-    // defense-in-depth requires us to validate `entry.name` before any
-    // filesystem write. A malicious or buggy upstream that hands us
-    // `../escape` must not be able to write outside the target.
+    // Even though GitHub returns trustworthy data, defense-in-depth requires
+    // us to validate every entry name before any filesystem write. A malicious
+    // or buggy upstream that hands us `../escape` must not write outside the
+    // target.
     const badFetch: FetchLike = (async (input: RequestInfo | URL) => {
       const url = typeof input === "string" ? input : input.toString();
-      if (url.includes("api.github.com")) {
+      if (url.includes("marketplace.json")) {
+        return new Response("not found", { status: 404 });
+      }
+      if (url.includes("/contents/")) {
         return new Response(
           JSON.stringify([
             {
               name: "../escape",
               path: "experimental/plugins/demo/../escape",
               type: "file",
-              size: 1,
-              download_url:
-                "https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/experimental/plugins/demo/escape",
+              download_url: `${DOWNLOAD_HOST}escape`,
             },
           ]),
-          { status: 200, headers: { "content-type": "application/json" } },
+          { status: 200 },
         );
       }
       return new Response("x", { status: 200 });
@@ -335,6 +473,186 @@ describe("installPlugin", () => {
   });
 });
 
+describe("installPlugin — marketplace resolution", () => {
+  let ws: string;
+  let pluginsDir: string;
+
+  beforeEach(() => {
+    ws = mkdtempSync(join(tmpdir(), "vellum-plugins-mkt-"));
+    pluginsDir = join(ws, "plugins");
+    mkdirSync(pluginsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(ws, { recursive: true, force: true });
+  });
+
+  const CAVEMAN_MANIFEST = {
+    name: "vellum-assistant",
+    plugins: [
+      {
+        name: "caveman",
+        source: {
+          source: "github",
+          repo: "JuliusBrussee/caveman",
+          ref: "v1.8.2",
+        },
+        description: "Ultra-compressed communication mode.",
+      },
+    ],
+  };
+
+  test("installs a whitelisted plugin by shallow-cloning its pinned repo + ref", async () => {
+    // GIVEN a marketplace whitelisting caveman at its repo root, pinned to a tag
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const calls: string[][] = [];
+    const runGit = fakeGitRunner({
+      tree: {
+        "package.json": '{"name":"caveman"}',
+        "README.md": "# caveman",
+        ".claude-plugin": null,
+        ".claude-plugin/plugin.json": "{}",
+      },
+      commit: "1111111222222233333334444444555555666666",
+      calls,
+    });
+
+    // WHEN we install by name (the install ref is ignored in favor of the
+    // manifest's pinned ref)
+    const result = await installPlugin(
+      { name: "caveman", ref: "main" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the external tree is materialized under <pluginsDir>/caveman, the
+    // result reports the pinned ref and resolved commit, and `.git` is dropped
+    const target = join(pluginsDir, "caveman");
+    expect(result.target).toBe(target);
+    expect(result.ref).toBe("v1.8.2");
+    expect(result.commit).toBe("1111111222222233333334444444555555666666");
+    expect(result.fileCount).toBe(3);
+    expect(readFileSync(join(target, "package.json"), "utf-8")).toBe(
+      '{"name":"caveman"}',
+    );
+    expect(existsSync(join(target, ".claude-plugin", "plugin.json"))).toBe(
+      true,
+    );
+    expect(existsSync(join(target, ".git"))).toBe(false);
+
+    // AND the clone fetched the pinned ref from the pinned repo URL.
+    const fetchCall = calls.find((c) => c[0] === "fetch");
+    expect(fetchCall).toContain("v1.8.2");
+    const remoteCall = calls.find((c) => c[0] === "remote");
+    expect(remoteCall?.at(-1)).toBe(
+      "https://github.com/JuliusBrussee/caveman.git",
+    );
+
+    // AND a provenance manifest records the external source + commit.
+    const manifest = JSON.parse(
+      readFileSync(join(target, ".vellum-plugin.json"), "utf-8"),
+    );
+    expect(manifest.source.kind).toBe("external");
+    expect(manifest.source.owner).toBe("JuliusBrussee");
+    expect(manifest.source.ref).toBe("v1.8.2");
+    expect(manifest.commit).toBe("1111111222222233333334444444555555666666");
+  });
+
+  test("a missing remote ref surfaces a clean not-found", async () => {
+    // GIVEN a clone whose fetch fails because the ref doesn't exist
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({
+      tree: {},
+      fetchError: Object.assign(new Error("git fetch failed"), {
+        stderr: "fatal: couldn't find remote ref v1.8.2",
+      }),
+    });
+
+    // WHEN we install
+    // THEN it is a hard not-found, not a retryable error
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotFoundError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("a network failure during clone surfaces a retryable error", async () => {
+    // GIVEN a clone whose fetch fails with a transient network error
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({
+      tree: {},
+      fetchError: Object.assign(new Error("git fetch failed"), {
+        stderr: "fatal: unable to access: Could not resolve host: github.com",
+      }),
+    });
+
+    // WHEN we install
+    // THEN it surfaces as the retryable variant so the route maps it to 503
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginSourceUnavailableError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("a name absent from the manifest falls back to the first-party source", async () => {
+    // GIVEN a manifest that does NOT whitelist "simple-memory", and no such
+    // first-party tree in the canonical repo
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+
+    // WHEN we install a first-party name
+    // THEN resolution falls back to the first-party path and surfaces a clean
+    // not-found pointing at the first-party source (git is never invoked)
+    await expect(
+      installPlugin(
+        { name: "simple-memory", ref: "main" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toMatchObject({
+      constructor: PluginNotFoundError,
+      message: expect.stringContaining("vellum-ai/vellum-assistant"),
+    });
+  });
+
+  test("first-party plugin wins a name collision with the marketplace", async () => {
+    // GIVEN a manifest whitelisting "caveman" externally
+    // AND an in-repo first-party plugin that also claims the name "caveman"
+    const fetch = makeContentsFetch({
+      tree: {
+        "experimental/plugins/caveman/package.json":
+          '{"name":"@vellumai/caveman"}',
+        "experimental/plugins/caveman/hooks": null,
+        "experimental/plugins/caveman/hooks/init.ts": "// first-party",
+      },
+      manifest: CAVEMAN_MANIFEST,
+    });
+
+    // WHEN we install by the colliding name (git must NOT run — the in-repo
+    // plugin is served entirely from the Contents API)
+    const result = await installPlugin(
+      { name: "caveman", ref: "main" },
+      { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the in-repo plugin is installed (matching what the search catalog
+    // advertises for the name), not the external repo — the marketplace is
+    // additive and never overrides a first-party plugin
+    const target = join(pluginsDir, "caveman");
+    expect(result.ref).toBe("main");
+    expect(result.commit).toBeNull();
+    expect(readFileSync(join(target, "package.json"), "utf-8")).toBe(
+      '{"name":"@vellumai/caveman"}',
+    );
+    expect(readFileSync(join(target, "hooks", "init.ts"), "utf-8")).toBe(
+      "// first-party",
+    );
+  });
+});
+
 describe("sanitizePluginName", () => {
   test.each([
     ["../escape"],