@stigmer/cli 3.18.0-dev.20260918103812 → 3.18.0

package/src/marketplace/config.test.ts

@@ -48,25 +48,38 @@ function writeConfig(yaml: string): void {
   writeFileSync(configPath(), yaml);
 }
 
+const BUILT_IN_NAMES = [
+  OFFICIAL_MARKETPLACE_NAME,
+  "cursor-plugins",
+  "claude-code-plugins",
+  "codex-plugins",
+];
+
 describe("listMarketplaces", () => {
-  it("is the official marketplace alone on a fresh machine", () => {
+  it("is the built-in sources alone on a fresh machine, the official one first", () => {
     const listing = listMarketplaces();
-    expect(listing.known.map((m) => m.name)).toEqual([
-      OFFICIAL_MARKETPLACE_NAME,
-    ]);
+    expect(listing.known.map((m) => m.name)).toEqual(BUILT_IN_NAMES);
     expect(listing.known[0]?.source).toEqual({ type: "official" });
+    expect(listing.known[1]?.source).toEqual({
+      type: "github",
+      repo: "cursor/plugins",
+    });
     expect(listing.unreadable).toEqual([]);
   });
 
-  it("lists configured entries after the official one, in file order, and names the unreadable ones", () => {
+  it("lists configured entries after the built-ins, in file order, names the unreadable ones, and lets a built-in win over a same-named entry", () => {
     writeConfig(
       [
         "backend:",
         "  type: local",
         "marketplaces:",
+        "  acme:",
+        "    type: github",
+        "    repo: acme/plugins",
+        // Written before the vendors were built in: the built-in wins, the entry stays in the file.
         "  cursor-plugins:",
         "    type: github",
-        "    repo: cursor/plugins",
+        "    repo: someone/fork",
         "  pinned:",
         "    type: github",
         "    repo: anthropics/claude-code",
@@ -84,24 +97,28 @@ describe("listMarketplaces", () => {
     );
     const listing = listMarketplaces();
     expect(listing.known.map((m) => m.name)).toEqual([
-      "stigmer",
-      "cursor-plugins",
+      ...BUILT_IN_NAMES,
+      "acme",
       "pinned",
       "team",
     ]);
-    expect(listing.known[1]?.source).toEqual({
+    expect(listing.known[4]?.source).toEqual({
       type: "github",
-      repo: "cursor/plugins",
+      repo: "acme/plugins",
     });
-    expect(listing.known[2]?.source).toEqual({
+    expect(listing.known[5]?.source).toEqual({
       type: "github",
       repo: "anthropics/claude-code",
       ref: "v1.2.3",
     });
-    expect(listing.known[3]?.source).toEqual({
+    expect(listing.known[6]?.source).toEqual({
       type: "local",
       path: "/srv/plugins",
     });
+    expect(listing.known[1]?.source).toEqual({
+      type: "github",
+      repo: "cursor/plugins",
+    });
     expect(listing.unreadable).toEqual([
       {
         name: "broken",
@@ -114,26 +131,26 @@ describe("listMarketplaces", () => {
 
 describe("addMarketplace and removeMarketplace", () => {
   it("round-trips a github source and a local source through the file", () => {
-    addMarketplace("cursor-plugins", {
+    addMarketplace("acme", {
       type: "github",
-      repo: "cursor/plugins",
+      repo: "acme/plugins",
     });
     addMarketplace("team", { type: "local", path: "/srv/plugins" });
     const text = readFileSync(configPath(), "utf8");
     expect(text).toContain("marketplaces:");
     expect(text).toContain("type: github");
-    expect(text).toContain("repo: cursor/plugins");
+    expect(text).toContain("repo: acme/plugins");
     expect(text).not.toContain("ref:");
     expect(text).toContain("path: /srv/plugins");
     expect(listMarketplaces().known.map((m) => m.name)).toEqual([
-      "stigmer",
-      "cursor-plugins",
+      ...BUILT_IN_NAMES,
+      "acme",
       "team",
     ]);
 
-    removeMarketplace("cursor-plugins");
+    removeMarketplace("acme");
     expect(listMarketplaces().known.map((m) => m.name)).toEqual([
-      "stigmer",
+      ...BUILT_IN_NAMES,
       "team",
     ]);
     removeMarketplace("team");
@@ -156,10 +173,13 @@ describe("addMarketplace and removeMarketplace", () => {
     });
   });
 
-  it("refuses the reserved name, a duplicate, an unknown removal, and the reserved removal", () => {
+  it("refuses every built-in name, a duplicate, an unknown removal, and a built-in removal", () => {
     expect(() =>
       addMarketplace("stigmer", { type: "local", path: "/x" }),
-    ).toThrow(/built-in marketplace/);
+    ).toThrow(/'stigmer' is a built-in source and cannot be added or replaced/);
+    expect(() =>
+      addMarketplace("cursor-plugins", { type: "local", path: "/x" }),
+    ).toThrow(/'cursor-plugins' is a built-in source/);
     addMarketplace("team", { type: "local", path: "/srv/plugins" });
     expect(() =>
       addMarketplace("team", { type: "local", path: "/other" }),
@@ -167,7 +187,12 @@ describe("addMarketplace and removeMarketplace", () => {
     expect(() => removeMarketplace("nope")).toThrow(
       /no marketplace named 'nope'/,
     );
-    expect(() => removeMarketplace("stigmer")).toThrow(/cannot be removed/);
+    expect(() => removeMarketplace("stigmer")).toThrow(
+      /'stigmer' is a built-in source and cannot be removed/,
+    );
+    expect(() => removeMarketplace("codex-plugins")).toThrow(
+      /'codex-plugins' is a built-in source and cannot be removed/,
+    );
   });
 
   it("refuses under --standalone instead of writing a default file over the user's", () => {

package/src/marketplace/config.ts

@@ -1,10 +1,14 @@
-// The marketplaces a CLI knows: the official one, built in, and the ones a
-// user added under the `marketplaces` key of ~/.stigmer/config.yaml.
+// The sources a CLI knows: the built-in ones (the official catalogue and the
+// three vendors' public ones, the same list the console ships), and the ones
+// a user added under the `marketplaces` key of ~/.stigmer/config.yaml.
 //
-// A marketplace is client-side configuration, never a server resource: the
+// A source is client-side configuration, never a server resource: the
 // server only ever sees the plugin archive a client pushes. That is why the
 // list lives beside the named backends and the context, and why `stigmer
-// marketplace` is a noun group like `config` and `auth`.
+// marketplace` is a noun group like `config` and `auth`. The built-ins are
+// code, not config: they cannot be added over or removed, so `stigmer
+// install cursor-plugins/thermos` works on a fresh machine and the CLI's
+// list never drifts from the console's.
 //
 // The config module keeps the on-disk entry loose (`MarketplaceEntryConfig`,
 // every field optional) so a hand-edited entry this CLI cannot read survives
@@ -20,8 +24,11 @@ import {
 } from "../config/index.js";
 import {
   type GitHubMarketplaceSource,
+  BUILT_IN_MARKETPLACES,
   OFFICIAL_MARKETPLACE_NAME,
+  builtInSourceRefusal,
   describeGitHubSource,
+  isBuiltInMarketplaceName,
   isOwnerRepo,
 } from "@stigmer/plugin-package/client";
 import { UsageError } from "../errors/index.js";
@@ -61,13 +68,23 @@ export const OFFICIAL_MARKETPLACE: KnownMarketplace = {
   source: { type: "official" },
 };
 
-/** Every marketplace the config names, the official one first. */
+/** The sources every CLI ships with, in listing order; the official one is first. */
+export const BUILT_IN_SOURCES: readonly KnownMarketplace[] =
+  BUILT_IN_MARKETPLACES.map((entry) => ({
+    name: entry.name,
+    source: entry.source,
+  }));
+
+/** Every source the CLI knows: the built-ins first, then the config's entries in file order. */
 export function listMarketplaces(
   config: Config = loadConfig(),
 ): MarketplaceListing {
-  const known: KnownMarketplace[] = [OFFICIAL_MARKETPLACE];
+  const known: KnownMarketplace[] = [...BUILT_IN_SOURCES];
   const unreadable: UnreadableMarketplace[] = [];
   for (const [name, entry] of Object.entries(config.marketplaces ?? {})) {
+    // A config written before the vendors were built in may name one; the
+    // built-in wins and the entry is left in the file untouched.
+    if (isBuiltInMarketplaceName(name)) continue;
     const narrowed = narrowEntry(entry);
     if (narrowed.ok) known.push({ name, source: narrowed.source });
     else unreadable.push({ name, reason: narrowed.reason });
@@ -106,9 +123,9 @@ export function addMarketplace(
   source: Exclude<MarketplaceSource, { type: "official" }>,
 ): void {
   refuseStandalone("add");
-  if (name === OFFICIAL_MARKETPLACE_NAME) {
+  if (isBuiltInMarketplaceName(name)) {
     throw new UsageError(
-      `'${OFFICIAL_MARKETPLACE_NAME}' is the built-in marketplace and cannot be added or replaced\n\n` +
+      `${builtInSourceRefusal(name, "add")}\n\n` +
         "Pass --name <other-name> to add this source under a different name.",
     );
   }
@@ -128,10 +145,8 @@ export function addMarketplace(
 /** Remove the marketplace called `name` and save. Refuses the reserved name and an unknown one. */
 export function removeMarketplace(name: string): void {
   refuseStandalone("remove");
-  if (name === OFFICIAL_MARKETPLACE_NAME) {
-    throw new UsageError(
-      `'${OFFICIAL_MARKETPLACE_NAME}' is the built-in marketplace and cannot be removed`,
-    );
+  if (isBuiltInMarketplaceName(name)) {
+    throw new UsageError(builtInSourceRefusal(name, "remove"));
   }
   const config = loadConfig();
   if (config.marketplaces?.[name] === undefined) {

package/src/marketplace/github.test.ts

@@ -2,7 +2,10 @@
 // its top directory stripped; every cap refuses naming itself, from the
 // central directory before anything inflates; an escaping path, a second
 // top-level directory and a lying declared size refuse; 404 and a network
-// failure carry their own exit codes.
+// failure carry their own exit codes. The peek reads one raw file, the first
+// of the four locations that exists, as declared; a repository with none is
+// not a marketplace, a refused file travels with its sentences, and a
+// network failure carries its exit code.
 
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -13,6 +16,8 @@ import { ExitCode } from "../errors/index.js";
 import {
   GITHUB_ZIPBALL_LIMITS,
   fetchGitHubTree,
+  peekGitHubMarketplace,
+  rawFileUrl,
   zipballUrl,
 } from "./github.js";
 
@@ -316,3 +321,74 @@ describe("fetchGitHubTree", () => {
     expect(offline.exitCode).toBe(ExitCode.Connection);
   });
 });
+
+/** A fetch answering raw.githubusercontent.com from a path map, 404 elsewhere. */
+function rawServing(
+  files: Record<string, string>,
+): typeof globalThis.fetch {
+  return async (input) => {
+    const url = String(input);
+    const prefix = "https://raw.githubusercontent.com/a/b/HEAD/";
+    const path = url.startsWith(prefix) ? url.slice(prefix.length) : undefined;
+    const content = path === undefined ? undefined : files[path];
+    return content === undefined
+      ? new Response("Not Found", { status: 404 })
+      : new Response(content, { status: 200 });
+  };
+}
+
+describe("rawFileUrl", () => {
+  it("names raw.githubusercontent.com at HEAD by default and the ref when given", () => {
+    expect(rawFileUrl({ repo: "a/b" }, ".cursor-plugin/marketplace.json")).toBe(
+      "https://raw.githubusercontent.com/a/b/HEAD/.cursor-plugin/marketplace.json",
+    );
+    expect(rawFileUrl({ repo: "a/b", ref: "v1" }, "marketplace.json")).toBe(
+      "https://raw.githubusercontent.com/a/b/v1/marketplace.json",
+    );
+  });
+});
+
+describe("peekGitHubMarketplace", () => {
+  it("reads the first location present in the library's precedence, as declared, tree unverified", async () => {
+    const peek = await peekGitHubMarketplace(
+      { repo: "a/b" },
+      rawServing({
+        ".cursor-plugin/marketplace.json": JSON.stringify({
+          name: "acme",
+          plugins: [{ name: "thermos", source: "thermos" }],
+        }),
+      }),
+    );
+    expect(peek.ok).toBe(true);
+    if (!peek.ok) return;
+    expect(peek.peeked.location).toBe(".cursor-plugin/marketplace.json");
+    expect(peek.peeked.marketplace.plugins.map((p) => p.name)).toEqual([
+      "thermos",
+    ]);
+  });
+
+  it("is not-a-marketplace when no location exists, and refused with the library's sentences when the file is broken", async () => {
+    expect(await peekGitHubMarketplace({ repo: "a/b" }, rawServing({}))).toEqual({
+      ok: false,
+      kind: "not-a-marketplace",
+    });
+    const refused = await peekGitHubMarketplace(
+      { repo: "a/b" },
+      rawServing({ "marketplace.json": JSON.stringify({ plugins: "no" }) }),
+    );
+    expect(refused.ok).toBe(false);
+    if (refused.ok || refused.kind !== "refused") throw new Error("expected refused");
+    expect(refused.location).toBe("marketplace.json");
+    expect(refused.errors.length).toBeGreaterThan(0);
+  });
+
+  it("carries the connection exit code when GitHub cannot be reached", async () => {
+    const offline = await peekGitHubMarketplace({ repo: "a/b" }, async () => {
+      throw new Error("ENOTFOUND");
+    }).catch((e: unknown) => e);
+    expect(offline).toMatchObject({
+      message: "could not reach GitHub for a/b",
+      exitCode: ExitCode.Connection,
+    });
+  });
+});

package/src/marketplace/github.ts

@@ -23,11 +23,27 @@
 // 1,169 entries; anthropics/claude-code 11.7 / 13.6 / 1,595; openai/codex
 // 18.6 / 76.8 / 9,188, its marketplace file at the repository root so the
 // whole repository is the tree), with room above the largest.
+//
+// The peek. A bare `stigmer install <name>` asks every known source whether
+// it offers the name, and with the vendors' catalogues built in that would be
+// three zipballs (about 35 MiB) per install. `peekGitHubMarketplace` reads
+// only the marketplace file instead: the four locations the library knows,
+// tried in its precedence, from raw.githubusercontent.com at the ref (no API
+// call, no token, no rate budget, the same reasons as the zipball). It
+// answers what the file declares; the zipball is then downloaded for the one
+// holder and the tree read verifies the entry before anything is installed.
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { inflateRawSync } from "node:zlib";
-import { isContainedPath } from "@stigmer/plugin-package";
+import {
+  MARKETPLACE_LOCATIONS,
+  type Marketplace,
+  type MarketplaceFinding,
+  inMemoryPluginFiles,
+  isContainedPath,
+  readMarketplaceFile,
+} from "@stigmer/plugin-package";
 import {
   type ZipStructuralEntry,
   crc32,
@@ -73,6 +89,104 @@ export function zipballUrl(source: GitHubTreeSource): string {
   return `https://codeload.github.com/${source.repo}/zip/${source.ref ?? DEFAULT_REF}`;
 }
 
+/** The URL raw.githubusercontent.com serves `path` from at `ref` (no API, no token). */
+export function rawFileUrl(source: GitHubTreeSource, path: string): string {
+  return `https://raw.githubusercontent.com/${source.repo}/${source.ref ?? DEFAULT_REF}/${path}`;
+}
+
+/** What a peek learned: the file as declared, and where it sat. */
+export interface PeekedMarketplace {
+  readonly marketplace: Marketplace;
+  readonly warnings: readonly MarketplaceFinding[];
+  /** The marketplace file's path in the tree, the first present in the library's precedence. */
+  readonly location: string;
+}
+
+export type PeekOutcome =
+  | { readonly ok: true; readonly peeked: PeekedMarketplace }
+  /** No marketplace file at any of the four locations: the repository is not a marketplace. */
+  | { readonly ok: false; readonly kind: "not-a-marketplace" }
+  /** A file was found and the library refused it; its sentences travel. */
+  | {
+      readonly ok: false;
+      readonly kind: "refused";
+      readonly location: string;
+      readonly errors: readonly MarketplaceFinding[];
+      readonly warnings: readonly MarketplaceFinding[];
+    };
+
+/**
+ * Read only the marketplace file of a GitHub source. The four locations are
+ * tried in the library's precedence and the first that exists is read as
+ * declared (`readMarketplaceFile`: the tree is not consulted). Network and
+ * server faults throw a `CliExitError` naming the repository, as the
+ * zipball download does; a 404 at every location is the `not-a-marketplace`
+ * outcome, not an error, because a bare-name search must say which sources
+ * it looked at and move on.
+ */
+export async function peekGitHubMarketplace(
+  source: GitHubTreeSource,
+  fetchImpl: typeof globalThis.fetch = globalThis.fetch,
+): Promise<PeekOutcome> {
+  for (const location of Object.values(MARKETPLACE_LOCATIONS)) {
+    const bytes = await fetchRawFile(source, location, fetchImpl);
+    if (bytes === undefined) continue;
+    const outcome = readMarketplaceFile(
+      inMemoryPluginFiles(new Map([[location, bytes]])),
+    );
+    if (!outcome.ok) {
+      return {
+        ok: false,
+        kind: "refused",
+        location,
+        errors: outcome.errors,
+        warnings: outcome.warnings,
+      };
+    }
+    return {
+      ok: true,
+      peeked: {
+        marketplace: outcome.marketplace,
+        warnings: outcome.warnings,
+        location,
+      },
+    };
+  }
+  return { ok: false, kind: "not-a-marketplace" };
+}
+
+/** One raw file, or `undefined` when the path does not exist at the ref. */
+async function fetchRawFile(
+  source: GitHubTreeSource,
+  path: string,
+  fetchImpl: typeof globalThis.fetch,
+): Promise<Uint8Array | undefined> {
+  const url = rawFileUrl(source, path);
+  let response: Response;
+  try {
+    response = await fetchImpl(url, { redirect: "follow" });
+  } catch (error) {
+    throw new CliExitError(
+      `could not reach GitHub for ${source.repo}`,
+      ExitCode.Connection,
+      [
+        `URL: ${url}`,
+        "Check the network connection and retry.",
+        error instanceof Error ? error.message : String(error),
+      ],
+    );
+  }
+  if (response.status === 404) return undefined;
+  if (!response.ok) {
+    throw new CliExitError(
+      `GitHub answered ${response.status} for ${source.repo}`,
+      ExitCode.Connection,
+      [`URL: ${url}`, "Retry; if it persists, the repository or GitHub is unavailable."],
+    );
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}
+
 /**
  * Download the zipball and extract it into `destDir` with the zipball's
  * single top-level directory (`<repo>-<ref>/`) stripped, so `destDir` IS the

package/src/marketplace/install.test.ts

@@ -1,8 +1,11 @@
 // Pins how a ref becomes a prepared push: an offered entry prepares through
 // the same walker `push plugin` uses (one digest for one tree); a version
-// pin is an assertion; a bare name is searched across the configured
-// marketplaces and must land in exactly one; every temp tree a search opened
-// is disposed, whatever the outcome.
+// pin is an assertion; a bare name is searched across the known sources and
+// must land in exactly one; a GitHub source is asked through its marketplace
+// file alone and its zipball fetched only when the file declares the name (a
+// repository with no file declares nothing; a declared entry the tree does
+// not hold is not a holder); every temp tree a search opened is disposed,
+// whatever the outcome.
 
 import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -44,7 +47,7 @@ describe("prepareEntry", () => {
   it("refuses an entry the marketplace does not offer, quoting the drop sentence when there is one", async () => {
     const tree = readMarketplaceTree(root);
     await expect(prepareEntry(tree, "ghost")).rejects.toThrow(
-      /does not offer a plugin named 'ghost'\n\n.*ghost.*\n\nRun 'stigmer marketplace show cursor-plugins' to see the 2 it offers/s,
+      /does not offer a plugin named 'ghost'\n\n.*ghost.*\n\nRun 'stigmer marketplace show acme-plugins' to see the 2 it offers/s,
     );
     await expect(prepareEntry(tree, "nope")).rejects.toThrow(
       /does not offer a plugin named 'nope'\n\nRun 'stigmer marketplace show/,
@@ -60,9 +63,9 @@ describe("assertVersion", () => {
       assertVersion(prepared, "1.0.0", "thermos@1.0.0"),
     ).not.toThrow();
     expect(() =>
-      assertVersion(prepared, "9.9.9", "cursor-plugins/thermos@9.9.9"),
+      assertVersion(prepared, "9.9.9", "acme-plugins/thermos@9.9.9"),
     ).toThrow(
-      /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0\n\nInstall it as 'cursor-plugins\/thermos@1\.0\.0'/,
+      /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0\n\nInstall it as 'acme-plugins\/thermos@1\.0\.0'/,
     );
   });
 });
@@ -70,16 +73,32 @@ describe("assertVersion", () => {
 describe("locateEntry", () => {
   const encoder = new TextEncoder();
 
-  /** A GitHub source served from memory: the fixture tree zipped under one top directory. */
+  /**
+   * A GitHub source served from memory: raw.githubusercontent.com answers a
+   * single file from the map (404 when absent), codeload answers the tree
+   * zipped under one top directory. `requests` records every URL asked.
+   */
   function servingZipOf(
     files: Record<string, string>,
     top = "r-HEAD",
+    requests: string[] = [],
   ): typeof globalThis.fetch {
     const tree: Record<string, Uint8Array> = {};
     for (const [path, content] of Object.entries(files))
       tree[`${top}/${path}`] = encoder.encode(content);
     const bytes = zipSync(tree);
-    return async () => new Response(bytes, { status: 200 });
+    return async (input) => {
+      const url = String(input);
+      requests.push(url);
+      const raw = url.match(/^https:\/\/raw\.githubusercontent\.com\/[^/]+\/[^/]+\/[^/]+\/(.+)$/);
+      if (raw !== null) {
+        const content = files[raw[1] ?? ""];
+        return content === undefined
+          ? new Response("Not Found", { status: 404 })
+          : new Response(content, { status: 200 });
+      }
+      return new Response(bytes, { status: 200 });
+    };
   }
 
   const remoteFiles = {
@@ -99,15 +118,15 @@ describe("locateEntry", () => {
 
   it("opens the marketplace a prefixed ref names and refuses an unknown prefix", async () => {
     const local = {
-      name: "cursor-plugins",
+      name: "acme-plugins",
       source: { type: "local", path: root } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("cursor-plugins/thermos"),
+      parseInstallRef("acme-plugins/thermos"),
       listing(local),
     );
     try {
-      expect(located.marketplace.name).toBe("cursor-plugins");
+      expect(located.marketplace.name).toBe("acme-plugins");
       expect(located.tree.root).toBe(root);
     } finally {
       located.open.dispose();
@@ -119,7 +138,7 @@ describe("locateEntry", () => {
 
   it("searches a bare name across every marketplace and lands in the one holder, disposing the rest", async () => {
     const local = {
-      name: "cursor-plugins",
+      name: "acme-plugins",
       source: { type: "local", path: root } as const,
     };
     const located = await locateEntry(
@@ -127,7 +146,7 @@ describe("locateEntry", () => {
       listing(local),
     );
     try {
-      expect(located.marketplace.name).toBe("cursor-plugins");
+      expect(located.marketplace.name).toBe("acme-plugins");
     } finally {
       located.open.dispose();
     }
@@ -135,7 +154,7 @@ describe("locateEntry", () => {
 
   it("refuses a bare name nobody offers, naming what was searched and what could not be read", async () => {
     const local = {
-      name: "cursor-plugins",
+      name: "acme-plugins",
       source: { type: "local", path: root } as const,
     };
     await expect(
@@ -144,13 +163,13 @@ describe("locateEntry", () => {
         unreadable: [{ name: "broken", reason: "x" }],
       }),
     ).rejects.toThrow(
-      /no configured marketplace offers a plugin named 'nope'\n\nSearched: stigmer, cursor-plugins\. Not searched.*broken/,
+      /no configured marketplace offers a plugin named 'nope'\n\nSearched: stigmer, acme-plugins\. Not searched.*broken/,
     );
   });
 
   it("refuses a bare name two marketplaces offer, naming each qualified ref, and leaves no temp tree behind", async () => {
     const local = {
-      name: "cursor-plugins",
+      name: "acme-plugins",
       source: { type: "local", path: root } as const,
     };
     const remote = {
@@ -163,11 +182,59 @@ describe("locateEntry", () => {
         fetchImpl: servingZipOf(remoteFiles),
       }),
     ).rejects.toThrow(
-      /offered by more than one marketplace: cursor-plugins, remote\n\nName the one you mean: cursor-plugins\/thermos or remote\/thermos/,
+      /offered by more than one marketplace: acme-plugins, remote\n\nName the one you mean: acme-plugins\/thermos or remote\/thermos/,
     );
     expect(countTempTrees()).toBe(before);
   });
 
+  it("asks a GitHub source through its marketplace file alone and downloads the zipball only for a holder", async () => {
+    const local = {
+      name: "acme-plugins",
+      source: { type: "local", path: root } as const,
+    };
+    const remote = {
+      name: "remote",
+      source: { type: "github", repo: "a/b" } as const,
+    };
+    const requests: string[] = [];
+    // `github` is offered by the local fixture alone: the remote is peeked, not downloaded.
+    const located = await locateEntry(parseInstallRef("github"), listing(local, remote), {
+      fetchImpl: servingZipOf(remoteFiles, "r-HEAD", requests),
+    });
+    located.open.dispose();
+    expect(requests.some((url) => url.startsWith("https://raw.githubusercontent.com/a/b/"))).toBe(true);
+    expect(requests.some((url) => url.startsWith("https://codeload.github.com/"))).toBe(false);
+  });
+
+  it("treats a GitHub repository with no marketplace file as declaring nothing, and a declared entry the tree lacks as not held", async () => {
+    const empty = {
+      name: "empty",
+      source: { type: "github", repo: "a/b" } as const,
+    };
+    await expect(
+      locateEntry(parseInstallRef("nope"), listing(empty), {
+        fetchImpl: servingZipOf({}),
+      }),
+    ).rejects.toThrow(/no configured marketplace offers a plugin named 'nope'\n\nSearched: stigmer, empty\./);
+
+    const phantom = {
+      name: "phantom",
+      source: { type: "github", repo: "a/b" } as const,
+    };
+    const before = countTempTrees();
+    await expect(
+      locateEntry(parseInstallRef("ghost"), listing(phantom), {
+        fetchImpl: servingZipOf({
+          "marketplace.json": JSON.stringify({
+            name: "phantom",
+            plugins: [{ name: "ghost", source: "./ghost" }],
+          }),
+        }),
+      }),
+    ).rejects.toThrow(/no configured marketplace offers a plugin named 'ghost'/);
+    expect(countTempTrees()).toBe(before);
+  });
+
   it("disposes a fetched tree when the located entry is released", async () => {
     const remote = {
       name: "remote",