@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.3

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

@@ -18,6 +18,11 @@ import {
 const MANIFEST_URL_PREFIX =
   "https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins/marketplace.json";
 
+// External marketplace refs must be full commit SHAs (immutable). Fixtures use
+// realistic 40-char hex object names rather than tags/branches.
+const CAVEMAN_SHA = "63a91ecadbf4c4719a4602a5abb00883f9966034";
+const NESTED_SHA = "0123456789abcdef0123456789abcdef01234567";
+
 /** Serve `body` (any value) as the raw manifest file at the manifest URL. */
 function manifestFetch(body: unknown, status = 200, raw?: string): FetchLike {
   return (async (input: RequestInfo | URL) => {
@@ -41,7 +46,7 @@ const VALID_MANIFEST = {
       source: {
         source: "github",
         repo: "JuliusBrussee/caveman",
-        ref: "v1.8.2",
+        ref: CAVEMAN_SHA,
       },
       description: "Ultra-compressed communication mode.",
       category: "productivity",
@@ -52,7 +57,7 @@ const VALID_MANIFEST = {
         source: "github",
         repo: "acme/monorepo",
         path: "packages/nested",
-        ref: "abc123",
+        ref: NESTED_SHA,
       },
     },
   ],
@@ -71,7 +76,7 @@ describe("fetchMarketplaceEntries", () => {
     expect(entries[0]!.source).toEqual({
       source: "github",
       repo: "JuliusBrussee/caveman",
-      ref: "v1.8.2",
+      ref: CAVEMAN_SHA,
     });
     expect(entries[1]!.source.path).toBe("packages/nested");
   });
@@ -123,6 +128,51 @@ describe("fetchMarketplaceEntries", () => {
     ).rejects.toBeInstanceOf(MarketplaceFetchError);
   });
 
+  test("rejects a mutable tag or branch ref (must be a full commit SHA)", async () => {
+    // GIVEN an entry whose source pins a mutable tag rather than a commit SHA
+    const fetch = manifestFetch({
+      name: "x",
+      plugins: [
+        {
+          name: "caveman",
+          source: {
+            source: "github",
+            repo: "JuliusBrussee/caveman",
+            ref: "v1.8.2",
+          },
+        },
+      ],
+    });
+
+    // WHEN / THEN the mutable ref is rejected: a retag could repoint it at
+    // attacker code the daemon later dynamically imports.
+    await expect(
+      fetchMarketplaceEntries({ fetch }, { ref: "main" }),
+    ).rejects.toBeInstanceOf(MarketplaceFetchError);
+  });
+
+  test("rejects an abbreviated commit SHA", async () => {
+    // GIVEN an entry whose source uses a short (ambiguous, non-pinning) SHA
+    const fetch = manifestFetch({
+      name: "x",
+      plugins: [
+        {
+          name: "caveman",
+          source: {
+            source: "github",
+            repo: "JuliusBrussee/caveman",
+            ref: "63a91ec",
+          },
+        },
+      ],
+    });
+
+    // WHEN / THEN only a full object name pins the install immutably
+    await expect(
+      fetchMarketplaceEntries({ fetch }, { ref: "main" }),
+    ).rejects.toBeInstanceOf(MarketplaceFetchError);
+  });
+
   test("rejects a manifest entry missing a pinned ref", async () => {
     // GIVEN an entry whose source omits the required ref
     const fetch = manifestFetch({
@@ -169,7 +219,7 @@ describe("resolveMarketplaceSource", () => {
       source: {
         source: "github",
         repo: "JuliusBrussee/caveman",
-        ref: "v1.8.2",
+        ref: CAVEMAN_SHA,
       },
     },
     {
@@ -178,7 +228,7 @@ describe("resolveMarketplaceSource", () => {
         source: "github",
         repo: "acme/monorepo",
         path: "packages/nested",
-        ref: "abc123",
+        ref: NESTED_SHA,
       },
     },
   ];
@@ -193,7 +243,7 @@ describe("resolveMarketplaceSource", () => {
       owner: "JuliusBrussee",
       repo: "caveman",
       path: "",
-      ref: "v1.8.2",
+      ref: CAVEMAN_SHA,
     });
   });
 
@@ -207,7 +257,7 @@ describe("resolveMarketplaceSource", () => {
       owner: "acme",
       repo: "monorepo",
       path: "packages/nested",
-      ref: "abc123",
+      ref: NESTED_SHA,
     });
   });
 

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

@@ -279,7 +279,7 @@ describe("searchPlugins", () => {
           source: {
             source: "github",
             repo: "JuliusBrussee/caveman",
-            ref: "v1.8.2",
+            ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
           },
           description: "Ultra-compressed communication mode.",
         },
@@ -311,12 +311,12 @@ describe("searchPlugins", () => {
     expect(result.matches).toEqual([
       {
         name: "caveman",
-        path: "github:JuliusBrussee/caveman@v1.8.2",
+        path: "github:JuliusBrussee/caveman@63a91ecadbf4c4719a4602a5abb00883f9966034",
         description: "Ultra-compressed communication mode.",
         source: {
           kind: "github",
           repo: "JuliusBrussee/caveman",
-          ref: "v1.8.2",
+          ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
         },
       },
       {
@@ -337,7 +337,7 @@ describe("searchPlugins", () => {
           source: {
             source: "github",
             repo: "JuliusBrussee/caveman",
-            ref: "v1.8.2",
+            ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
           },
         },
       ],
@@ -357,8 +357,8 @@ describe("searchPlugins", () => {
     expect(result.matches).toEqual([]);
   });
 
-  test("first-party dirs win a name collision with the marketplace", async () => {
-    // GIVEN both a first-party dir and a marketplace entry named "caveman"
+  test("a marketplace entry owns a name shared by an in-repo stub dir", async () => {
+    // GIVEN a marketplace entry named "caveman"
     const manifest = {
       name: "vellum-assistant",
       plugins: [
@@ -367,11 +367,13 @@ describe("searchPlugins", () => {
           source: {
             source: "github",
             repo: "JuliusBrussee/caveman",
-            ref: "v1.8.2",
+            ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
           },
         },
       ],
     };
+    // AND a same-named in-repo directory, which is caveman's adapter stub
+    // rather than a standalone first-party plugin
     const fetch: FetchLike = (async (input: RequestInfo | URL) => {
       const url = typeof input === "string" ? input : input.toString();
       if (url.includes("marketplace.json")) {
@@ -394,12 +396,17 @@ describe("searchPlugins", () => {
     // WHEN we search
     const result = await searchPlugins({ query: "caveman" }, { fetch });
 
-    // THEN only the first-party entry surfaces — the manifest is additive
+    // THEN the name surfaces once, as the external marketplace entry — the
+    // stub dir is its adapter overlay, not a competing first-party listing
     expect(result.matches).toEqual([
       {
         name: "caveman",
-        path: "experimental/plugins/caveman",
-        source: { kind: "first-party" },
+        path: "github:JuliusBrussee/caveman@63a91ecadbf4c4719a4602a5abb00883f9966034",
+        source: {
+          kind: "github",
+          repo: "JuliusBrussee/caveman",
+          ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
+        },
       },
     ]);
   });

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

@@ -9,6 +9,11 @@
  *      fetched with a shallow `git` clone at that ref — one network operation
  *      regardless of repo size, immune to GitHub's unauthenticated API
  *      rate-limit, and recording the exact resolved commit for provenance.
+ *      When we curate an adapter stub for the plugin (an
+ *      `experimental/plugins/<name>/` directory in this repo with a
+ *      `scripts.postinstall` command), the stub is overlaid onto the clone and
+ *      its postinstall runs to translate a foreign-ecosystem layout into the
+ *      shape Vellum's loader runs (see {@link applyAdapterStub}).
  *   2. Otherwise the first-party convention
  *      `vellum-ai/vellum-assistant/experimental/plugins/<name>/` at the
  *      configured ref, fetched via the GitHub Contents API (a small handful of
@@ -29,14 +34,16 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
+  readFileSync,
   renameSync,
   rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 
+import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import {
   fetchMarketplaceEntries,
@@ -82,6 +89,18 @@ export type GitRunner = (
   opts: { readonly cwd: string },
 ) => Promise<{ readonly stdout: string }>;
 
+/**
+ * Runs a plugin's postinstall adapter script in `cwd`. Injected so tests can
+ * assert the adapter is invoked (and simulate its effects) without spawning a
+ * real subprocess; production callers fall back to {@link defaultPostinstallRunner}.
+ */
+export type PostinstallRunner = (opts: {
+  /** The staged install directory the adapter transforms in place. */
+  readonly cwd: string;
+  /** Absolute path to the adapter script to execute. */
+  readonly script: string;
+}) => Promise<void>;
+
 /** Options that control which plugin to install and how. */
 export interface InstallPluginOptions {
   readonly name: string;
@@ -100,6 +119,8 @@ export interface InstallPluginDeps {
   readonly workspacePluginsDir?: string;
   /** Override the git runner used to clone external plugin sources. Falls back to {@link defaultGitRunner}. */
   readonly runGit?: GitRunner;
+  /** Override the runner used to execute a plugin's postinstall adapter. Falls back to {@link defaultPostinstallRunner}. */
+  readonly runPostinstall?: PostinstallRunner;
 }
 
 /** Successful install result. */
@@ -123,6 +144,22 @@ export class InvalidPluginNameError extends Error {
   }
 }
 
+/**
+ * A plugin's curated postinstall adapter failed — its `scripts.postinstall`
+ * command was malformed/unsupported, its script was missing, or the script
+ * exited non-zero. The install is aborted and rolled back rather than
+ * materializing a half-transformed, non-functional plugin.
+ */
+export class PluginPostinstallError extends Error {
+  constructor(
+    readonly pluginName: string,
+    detail: string,
+  ) {
+    super(`Postinstall adapter for "${pluginName}" failed: ${detail}`);
+    this.name = "PluginPostinstallError";
+  }
+}
+
 /** A plugin with the same name is already installed and `--force` was not passed. */
 export class PluginAlreadyInstalledError extends Error {
   constructor(
@@ -204,40 +241,18 @@ function firstPartySource(name: string, ref: string): PluginFetchSource {
   };
 }
 
-/**
- * Probe whether a first-party plugin directory exists at the given source.
- *
- * A transient listing failure resolves to `false` so a marketplace-claimed
- * name still reaches its external source — the rare collision guarantee gives
- * way to keeping the common external-only install path working under flaky
- * network conditions.
- */
-async function firstPartyPluginExists(
-  source: PluginFetchSource,
-  fetchFn: FetchLike,
-): Promise<boolean> {
-  try {
-    const entries = await listDir(
-      source.owner,
-      source.repo,
-      source.rootPath,
-      source.ref,
-      fetchFn,
-    );
-    return entries !== null && entries.length > 0;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Resolve a plugin name to concrete GitHub coordinates.
  *
- * First-party plugins win a name collision: a name claimed by the curated
- * marketplace is fetched from its pinned external repo only when no
- * `experimental/plugins/<name>` directory exists in-repo. This mirrors the
- * search catalog, where an in-repo plugin suppresses a same-named marketplace
- * entry — install must advertise and install the same source.
+ * A name claimed by the curated marketplace resolves to its pinned external
+ * repo; any other name resolves to the first-party `experimental/plugins/<name>`
+ * convention. The marketplace is external-only by construction — a same-named
+ * `experimental/plugins/<name>` directory is the plugin's optional *adapter
+ * stub* (a curated `package.json` + postinstall script overlaid onto the clone
+ * to translate it into Vellum's shape; see {@link applyAdapterStub}), not a
+ * standalone first-party plugin. So letting the marketplace win the name is
+ * what makes the stub apply to the external clone, and the search catalog
+ * surfaces the same name as external — install and search stay in agreement.
  *
  * A missing or malformed manifest degrades to first-party resolution — the
  * whitelist is supplementary and must never block installing a first-party
@@ -259,12 +274,7 @@ async function resolvePluginSource(
     // Degrade to first-party resolution below.
   }
 
-  const firstParty = firstPartySource(name, marketplaceRef);
-  if (!resolved) return firstParty;
-
-  if (await firstPartyPluginExists(firstParty, fetchFn)) {
-    return firstParty;
-  }
+  if (!resolved) return firstPartySource(name, marketplaceRef);
 
   return {
     kind: "external",
@@ -363,6 +373,14 @@ export async function installPlugin(
       );
       fileCount = cloned.fileCount;
       commit = cloned.commit;
+      // An external clone is often a foreign-ecosystem plugin (e.g. a Claude
+      // Code plugin) that the Vellum loader can't run as-is. When we curate an
+      // adapter stub for it, overlay the stub and run its transform so the
+      // materialized tree is a valid Vellum plugin. Raw clones (no stub) are
+      // left untouched.
+      if (fileCount > 0) {
+        await applyAdapterStub(name, marketplaceRef, stagingDir, deps);
+      }
     } else {
       fileCount = await copyDir(
         source.owner,
@@ -372,6 +390,27 @@ export async function installPlugin(
         stagingDir,
         deps.fetch,
       );
+      // We only land in the first-party branch for this name when the
+      // marketplace lookup returned no claim. A *healthy* marketplace that
+      // claims the name routes to the external+adapter branch above; reaching
+      // here for a directory that is actually an adapter stub (declares a
+      // `scripts.postinstall`) therefore means the marketplace failed to load
+      // (rate-limit / 5xx / malformed) and we degraded past it. A stub has no
+      // hooks/tools of its own — it only transforms an external clone — so
+      // installing it alone would materialize a non-functional plugin. Fail
+      // loudly and retryably instead of silently shipping a broken plugin.
+      // Genuine first-party plugins (no postinstall) install normally.
+      if (
+        fileCount > 0 &&
+        resolvePostinstallScript(name, stagingDir) !== null
+      ) {
+        throw new PluginPostinstallError(
+          name,
+          "resolved to a first-party adapter stub, but its marketplace entry " +
+            "could not be read to locate the external source it adapts — the " +
+            "marketplace lookup likely failed transiently. Retry the install.",
+        );
+      }
     }
   } catch (err) {
     rmSync(stagingDir, { recursive: true, force: true });
@@ -446,7 +485,7 @@ async function copyExternalViaGit(
       // transient GitHub outage — is retryable, so map it to a 503.
       if (isGitRefNotFound(err)) return { fileCount: 0, commit: null };
       throw new PluginSourceUnavailableError(
-        `git clone failed for ${sourceLabel(source)} @ ${source.ref}: ${gitErrorText(err)}`,
+        `git clone failed for ${sourceLabel(source)} @ ${source.ref}: ${subprocessErrorText(err)}`,
         503,
       );
     }
@@ -462,6 +501,18 @@ async function copyExternalViaGit(
       commit = null;
     }
 
+    // Defense in depth: external marketplace refs are full commit SHAs (the
+    // manifest schema rejects mutable tags/branches), so the checked-out
+    // commit must equal the requested ref. If it ever diverges, refuse the
+    // install rather than materialize and `import()` unexpected code.
+    if (commit && commit.toLowerCase() !== source.ref.toLowerCase()) {
+      throw new PluginSourceUnavailableError(
+        `git checkout of ${sourceLabel(source)} resolved to ${commit}, ` +
+          `which does not match the pinned commit ${source.ref}`,
+        502,
+      );
+    }
+
     const srcRoot = source.rootPath
       ? join(cloneDir, source.rootPath)
       : cloneDir;
@@ -476,6 +527,172 @@ async function copyExternalViaGit(
   }
 }
 
+/** Cap on a postinstall adapter; the curated transforms are fast and file-only. */
+const POSTINSTALL_TIMEOUT_MS = 60_000;
+
+/**
+ * Overlay our curated adapter stub onto a freshly cloned external plugin and
+ * run its postinstall transform, returning whether a transform ran.
+ *
+ * The stub lives at `experimental/plugins/<name>/` in our own repo and carries
+ * a `package.json` (with a `scripts.postinstall` adapter command) plus the
+ * adapter script it names. We fetch it via the Contents API — a couple of
+ * small files, well within the rate limit — and copy it over the clone, which
+ * deliberately overwrites the clone's `package.json` so the postinstall we run
+ * is ours, never the upstream repo's lifecycle script. Absent a stub (the
+ * common case for a plugin already in Vellum shape), nothing is overlaid and
+ * the clone is installed as-is.
+ *
+ * On any adapter failure the error propagates so {@link installPlugin} rolls
+ * back staging — better to fail loudly than ship a half-transformed plugin.
+ */
+async function applyAdapterStub(
+  name: string,
+  ref: string,
+  stagingDir: string,
+  deps: InstallPluginDeps,
+): Promise<boolean> {
+  const stubFileCount = await copyDir(
+    PLUGIN_SOURCE_OWNER,
+    PLUGIN_SOURCE_REPO,
+    `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
+    ref,
+    stagingDir,
+    deps.fetch,
+  );
+  if (stubFileCount === 0) return false;
+
+  const script = resolvePostinstallScript(name, stagingDir);
+  if (script === null) return false;
+
+  const run = deps.runPostinstall ?? defaultPostinstallRunner;
+  try {
+    await run({ cwd: stagingDir, script });
+  } catch (err) {
+    throw new PluginPostinstallError(name, subprocessErrorText(err));
+  }
+  return true;
+}
+
+/**
+ * Resolve the absolute path of the adapter script named by the (overlaid stub)
+ * `package.json`'s `scripts.postinstall`, or `null` when there is no stub
+ * package.json / postinstall script.
+ *
+ * Curated adapters declare a single `bun <script>` invocation; bun is resolved
+ * via {@link ensureBun} at execution time (see {@link defaultPostinstallRunner})
+ * so the `bun` token marks the convention without hard-coding the binary path.
+ * Anything else — extra args, a shell pipeline, a non-script file — is rejected
+ * rather than executed, and the script path is constrained to a file inside the
+ * staging dir so a stub can never escape it.
+ */
+function resolvePostinstallScript(
+  name: string,
+  stagingDir: string,
+): string | null {
+  const pkgPath = join(stagingDir, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    return null;
+  }
+
+  const scripts =
+    typeof parsed === "object" && parsed !== null && "scripts" in parsed
+      ? (parsed as { scripts?: unknown }).scripts
+      : undefined;
+  const command =
+    typeof scripts === "object" && scripts !== null && "postinstall" in scripts
+      ? (scripts as { postinstall?: unknown }).postinstall
+      : undefined;
+  if (typeof command !== "string" || command.trim() === "") return null;
+
+  const match = /^bun\s+(\S+)$/.exec(command.trim());
+  if (!match) {
+    throw new PluginPostinstallError(
+      name,
+      `unsupported postinstall command ${JSON.stringify(command)} — ` +
+        "curated adapters must be a single `bun <script>` invocation",
+    );
+  }
+
+  let rel = match[1]!;
+  if (rel.startsWith("./")) rel = rel.slice(2);
+  if (!/\.(?:ts|mts|cts|mjs|cjs|js)$/.test(rel)) {
+    throw new PluginPostinstallError(
+      name,
+      `postinstall script ${JSON.stringify(rel)} must be a ` +
+        ".ts/.mts/.cts/.mjs/.cjs/.js file",
+    );
+  }
+  for (const segment of rel.split("/")) {
+    assertSafeFilename("postinstall script segment", segment);
+  }
+
+  const abs = resolve(stagingDir, rel);
+  if (
+    abs !== resolve(stagingDir) &&
+    !abs.startsWith(`${resolve(stagingDir)}${sep}`)
+  ) {
+    throw new PluginPostinstallError(
+      name,
+      `postinstall script ${JSON.stringify(rel)} escapes the plugin directory`,
+    );
+  }
+  if (!existsSync(abs)) {
+    throw new PluginPostinstallError(
+      name,
+      `postinstall script ${JSON.stringify(rel)} was not found in the plugin`,
+    );
+  }
+  return abs;
+}
+
+/**
+ * Production postinstall runner: executes the adapter with a real `bun` binary
+ * resolved via {@link ensureBun}, under a stripped environment and a timeout.
+ *
+ * `process.execPath` is unusable here: inside a `bun build --compile` binary it
+ * is the compiled assistant app, not the bun CLI (see `util/bun-runtime.ts`),
+ * so passing the adapter script to it would launch the daemon rather than
+ * interpret the script. `ensureBun()` locates (or downloads) a standalone bun
+ * the same way every other subsystem that spawns bun does. The minimal env
+ * (bun's dir + standard bins, `HOME` only) keeps the adapter from inheriting
+ * surprising config while still finding the runtime.
+ */
+export const defaultPostinstallRunner: PostinstallRunner = async ({
+  cwd,
+  script,
+}) => {
+  const bun = await ensureBun();
+  await execFileAsync(bun, [script], {
+    cwd,
+    encoding: "utf8",
+    timeout: POSTINSTALL_TIMEOUT_MS,
+    maxBuffer: 16 * 1024 * 1024,
+    env: pluginPostinstallEnv(bun),
+  });
+};
+
+function pluginPostinstallEnv(bun: string): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    PATH: [
+      dirname(bun),
+      "/opt/homebrew/bin",
+      "/usr/local/bin",
+      "/usr/bin",
+      "/bin",
+    ]
+      .filter(Boolean)
+      .join(":"),
+  };
+  if (process.env.HOME) env.HOME = process.env.HOME;
+  return env;
+}
+
 /**
  * Recursively copy regular files from `srcRoot` into `destDir`, skipping the
  * top-level `.git` directory and any symlinks. Returns the file count.
@@ -509,7 +726,7 @@ function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
 
 /** True when a git fetch failed because the repo or ref is unreachable. */
 function isGitRefNotFound(err: unknown): boolean {
-  const text = gitErrorText(err).toLowerCase();
+  const text = subprocessErrorText(err).toLowerCase();
   return [
     "could not find remote ref",
     "couldn't find remote ref",
@@ -523,7 +740,7 @@ function isGitRefNotFound(err: unknown): boolean {
 }
 
 /** Extract a stderr/message blob from a spawn error for classification/logging. */
-function gitErrorText(err: unknown): string {
+function subprocessErrorText(err: unknown): string {
   if (err instanceof Error) {
     const withStreams = err as Error & { stderr?: unknown };
     const stderr =

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

@@ -14,9 +14,10 @@
  *      `package.json` fields the manifest doesn't carry.
  *
  * Name-collision precedence matches {@link ./search-plugins} and
- * {@link ./install-from-github}: a first-party in-repo plugin wins a name also
- * claimed by the marketplace, so the detail page advertises the same source the
- * catalog and installer would use.
+ * {@link ./install-from-github}: a marketplace entry owns its name, so the
+ * detail page advertises the external source the catalog and installer use. A
+ * same-named `experimental/plugins/<name>/` directory is that plugin's adapter
+ * stub, not a standalone first-party plugin, so it does not override the claim.
  *
  * Designed for direct programmatic use with an injected `fetch`, mirroring the
  * sibling plugin libraries.
@@ -130,22 +131,28 @@ export async function getPluginDetails(
   const local = readLocalPlugin(pluginsDir, name);
 
   const marketplaceEntry = await findMarketplaceEntry(name, ref, fetchFn);
-  const firstPartyEntries = await listDirSafe(
-    PLUGIN_SOURCE_OWNER,
-    PLUGIN_SOURCE_REPO,
-    `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
-    ref,
-    fetchFn,
-  );
+
+  // A marketplace entry owns its name (the same-named in-repo directory, if
+  // any, is its adapter stub) — so only probe the first-party directory when
+  // the name is unclaimed, which also spares a GitHub request in the common
+  // external case.
+  const firstPartyEntries =
+    marketplaceEntry === null
+      ? await listDirSafe(
+          PLUGIN_SOURCE_OWNER,
+          PLUGIN_SOURCE_REPO,
+          `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
+          ref,
+          fetchFn,
+        )
+      : null;
   const firstPartyExists = firstPartyEntries !== null;
 
   if (!local.installed && !firstPartyExists && !marketplaceEntry) {
     throw new PluginDetailsNotFoundError(name, ref);
   }
 
-  // First-party wins a name collision, so probe the in-repo directory before
-  // honouring a marketplace claim — the same precedence the catalog applies.
-  const useExternal = !firstPartyExists && marketplaceEntry !== null;
+  const useExternal = marketplaceEntry !== null;
 
   const source: PluginMatchSource = useExternal
     ? {