@vellumai/assistant 0.8.8 → 0.8.9-staging.2

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

@@ -0,0 +1,84 @@
+/**
+ * In-memory cache for the installable plugin catalog.
+ *
+ * The catalog (`loadPluginCatalog`) is built from two unauthenticated GitHub
+ * Contents API calls — the first-party `experimental/plugins/` directory
+ * listing and the `marketplace.json` manifest. GitHub's unauthenticated rate
+ * limit is 60 requests/hour per IP, so a long-lived daemon that hit GitHub on
+ * every catalog search (on web mount, on every keystroke, across reloads and
+ * multiple clients) would exhaust that budget and start getting HTTP 403s.
+ *
+ * Because the GitHub responses are **query-independent** — `searchPlugins`
+ * applies the regex filter in memory — one catalog load serves any number of
+ * searches. This cache holds that load per git ref for a short TTL and, on an
+ * upstream failure, serves the last good catalog so a transient rate-limit or
+ * outage is invisible to callers. Mirrors the skills catalog cache
+ * (`src/skills/catalog-cache.ts`).
+ */
+
+import { getLogger } from "../../util/logger.js";
+import {
+  loadPluginCatalog,
+  type PluginCatalog,
+  PluginCatalogUnavailableError,
+  type SearchPluginsDeps,
+} from "./search-plugins.js";
+
+const log = getLogger("plugin-catalog-cache");
+
+/** How long a fetched catalog is served before a refresh is attempted. */
+export const PLUGIN_CATALOG_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+interface CacheEntry {
+  catalog: PluginCatalog;
+  timestamp: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Resolve the full plugin catalog at {@link ref} with in-memory caching.
+ *
+ * Within the TTL window the cached catalog is returned without touching the
+ * network. After the TTL elapses a refresh is attempted; if it fails with a
+ * transient upstream error ({@link PluginCatalogUnavailableError} — rate
+ * limiting or a 5xx) and a cached catalog exists, the stale catalog is served
+ * (and its TTL window is reset so a sustained outage doesn't re-enter the
+ * failing fetch on every call). A hard error (e.g. the canonical plugins
+ * prefix returning 404, or a deleted ref) always propagates — serving stale
+ * there would silently mask a real misconfiguration. With no cache to fall
+ * back on, the underlying error propagates regardless so the caller can
+ * surface it (e.g. the route maps a rate-limit failure to 503).
+ */
+export async function getPluginCatalog(
+  ref: string,
+  deps: SearchPluginsDeps,
+): Promise<PluginCatalog> {
+  const cached = cache.get(ref);
+  if (cached && Date.now() - cached.timestamp < PLUGIN_CATALOG_CACHE_TTL_MS) {
+    return cached.catalog;
+  }
+
+  try {
+    const catalog = await loadPluginCatalog({ ref }, deps);
+    cache.set(ref, { catalog, timestamp: Date.now() });
+    return catalog;
+  } catch (err) {
+    if (cached && err instanceof PluginCatalogUnavailableError) {
+      log.warn(
+        { err, ref },
+        "Failed to refresh plugin catalog, serving stale cache",
+      );
+      // Reset the TTL window so subsequent calls during the outage are served
+      // from cache instead of re-entering loadPluginCatalog() every time.
+      cached.timestamp = Date.now();
+      return cached.catalog;
+    }
+    throw err;
+  }
+}
+
+/** Invalidate the cache (for testing or forced refresh). */
+export function invalidatePluginCatalogCache(): void {
+  cache.clear();
+}

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

@@ -0,0 +1,409 @@
+/**
+ * Resolve a single plugin's detail view: tracked metadata plus its README.
+ *
+ * Powers the daemon's `GET /v1/plugins/:name` route and, through it, the web
+ * plugin detail page. The detail view unions three sources, preferring the
+ * most authoritative for each field:
+ *   1. The locally installed copy under `<workspacePluginsDir>/<name>/`, when
+ *      present — its `package.json` and `README.md` are read straight off disk.
+ *   2. The curated `experimental/plugins/marketplace.json` entry, for external
+ *      ecosystem plugins (description / homepage / license / pinned source).
+ *   3. The plugin's own repository at the pinned ref (first-party
+ *      `experimental/plugins/<name>/` or the external `owner/repo[/path]`),
+ *      fetched via the GitHub Contents API for the README and any
+ *      `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.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring the
+ * sibling plugin libraries.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  DEFAULT_PLUGIN_REF,
+  type FetchLike,
+  sanitizePluginName,
+} from "./install-from-github.js";
+import {
+  fetchMarketplaceEntries,
+  type MarketplaceEntry,
+} from "./plugin-marketplace.js";
+import type { PluginMatchSource } from "./search-plugins.js";
+
+const PLUGIN_SOURCE_OWNER = "vellum-ai";
+const PLUGIN_SOURCE_REPO = "vellum-assistant";
+const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
+
+/** Recognised README filenames, matched case-insensitively against a listing. */
+const README_RE = /^readme(\.md|\.markdown)?$/i;
+
+/** Entry shape returned by the GitHub Contents API for a directory listing. */
+interface GitHubContentEntry {
+  readonly name: string;
+  readonly path: string;
+  readonly type: "file" | "dir" | "symlink" | "submodule";
+  readonly download_url: string | null;
+}
+
+/** The subset of `package.json` fields the detail view surfaces. */
+interface PluginManifestFields {
+  readonly version: string | null;
+  readonly description: string | null;
+  readonly homepage: string | null;
+  readonly license: string | null;
+}
+
+/** Options that control which plugin to resolve and at what ref. */
+export interface PluginDetailsOptions {
+  /** Install name (kebab-case directory name). */
+  readonly name: string;
+  /** Git ref to read catalog metadata / README from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface PluginDetailsDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/** Resolved detail view for a single plugin. */
+export interface PluginDetails {
+  /** Install name. Matches `assistant plugins install <name>`. */
+  readonly name: string;
+  /** Whether a copy is materialized under the workspace plugins directory. */
+  readonly installed: boolean;
+  /** Short description, best-effort across the three sources; `null` when unknown. */
+  readonly description: string | null;
+  /** Project homepage URL, when known; `null` otherwise. */
+  readonly homepage: string | null;
+  /** SPDX license expression, when known; `null` otherwise. */
+  readonly license: string | null;
+  /** Resolved version (installed copy first, then repo `package.json`); `null` when unknown. */
+  readonly version: string | null;
+  /** Discriminated origin, mirroring the catalog's {@link PluginMatchSource}. */
+  readonly source: PluginMatchSource;
+  /** README markdown, or `null` when the plugin ships none. */
+  readonly readme: string | null;
+  /** Git ref the catalog metadata / README were resolved at. */
+  readonly ref: string;
+}
+
+/** No installed copy and no catalog/source entry claims the name. */
+export class PluginDetailsNotFoundError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly ref: string,
+  ) {
+    super(`Plugin "${pluginName}" not found in the catalog (ref ${ref}).`);
+    this.name = "PluginDetailsNotFoundError";
+  }
+}
+
+/**
+ * Resolve the detail view for {@link opts.name}.
+ *
+ * Throws {@link PluginDetailsNotFoundError} when the name is neither installed
+ * locally nor present in the catalog (first-party directory or marketplace
+ * entry). Network failures while enriching from GitHub degrade to the fields
+ * already known from disk / the manifest rather than failing the whole view —
+ * a detail page that renders metadata without a README beats a hard error.
+ */
+export async function getPluginDetails(
+  opts: PluginDetailsOptions,
+  deps: PluginDetailsDeps,
+): Promise<PluginDetails> {
+  const name = sanitizePluginName(opts.name);
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+  const { fetch: fetchFn } = deps;
+
+  const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
+  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,
+  );
+  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 source: PluginMatchSource = useExternal
+    ? {
+        kind: "github",
+        repo: marketplaceEntry!.source.repo,
+        ref: marketplaceEntry!.source.ref,
+        ...(marketplaceEntry!.source.path
+          ? { path: marketplaceEntry!.source.path }
+          : {}),
+      }
+    : { kind: "first-party" };
+
+  const remote = await readRemotePlugin(source, firstPartyEntries, fetchFn);
+
+  const readme = local.readme ?? remote.readme;
+
+  return {
+    name,
+    installed: local.installed,
+    description:
+      local.manifest.description ??
+      marketplaceEntry?.description ??
+      remote.manifest.description ??
+      null,
+    homepage:
+      local.manifest.homepage ??
+      marketplaceEntry?.homepage ??
+      remote.manifest.homepage ??
+      null,
+    license:
+      local.manifest.license ??
+      marketplaceEntry?.license ??
+      remote.manifest.license ??
+      null,
+    version: local.manifest.version ?? remote.manifest.version ?? null,
+    source,
+    readme,
+    ref,
+  };
+}
+
+interface LocalPlugin {
+  readonly installed: boolean;
+  readonly manifest: PluginManifestFields;
+  readonly readme: string | null;
+}
+
+/** Read an installed copy's `package.json` + README off disk, if present. */
+function readLocalPlugin(pluginsDir: string, name: string): LocalPlugin {
+  const target = join(pluginsDir, name);
+  if (!existsSync(target)) {
+    return { installed: false, manifest: emptyManifest(), readme: null };
+  }
+
+  const pkgPath = join(target, "package.json");
+  let manifest = emptyManifest();
+  if (existsSync(pkgPath)) {
+    try {
+      manifest = parseManifest(readFileSync(pkgPath, "utf8"));
+    } catch {
+      // A malformed local manifest degrades to empty fields — the entry is
+      // still "installed", we just have nothing extra to surface from it.
+    }
+  }
+
+  return { installed: true, manifest, readme: readLocalReadme(target) };
+}
+
+/** Find a README file in a directory listing and read it, if any. */
+function readLocalReadme(dir: string): string | null {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const readme = names.find((n) => README_RE.test(n));
+  if (!readme) return null;
+  try {
+    return readFileSync(join(dir, readme), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+interface RemotePlugin {
+  readonly manifest: PluginManifestFields;
+  readonly readme: string | null;
+}
+
+/**
+ * Fetch README + `package.json` from the plugin's repository.
+ *
+ * For a first-party plugin the listing is the in-repo directory the caller
+ * already fetched at the catalog ref (passed through to avoid a duplicate
+ * request). For an external plugin we list its `owner/repo[/path]` directory
+ * fresh at the plugin's own pinned `source.ref`.
+ */
+async function readRemotePlugin(
+  source: PluginMatchSource,
+  firstPartyEntries: readonly GitHubContentEntry[] | null,
+  fetchFn: FetchLike,
+): Promise<RemotePlugin> {
+  let owner: string;
+  let repo: string;
+  let entries: readonly GitHubContentEntry[] | null;
+
+  if (source.kind === "github") {
+    [owner, repo] = source.repo.split("/", 2) as [string, string];
+    // Read the external repo at its pinned ref, not the assistant catalog ref —
+    // the detail page must describe the same artifact the installer resolves
+    // from `source.ref`, even when that differs from the catalog ref (`main`).
+    entries = await listDirSafe(
+      owner,
+      repo,
+      source.path ?? "",
+      source.ref,
+      fetchFn,
+    );
+  } else {
+    owner = PLUGIN_SOURCE_OWNER;
+    repo = PLUGIN_SOURCE_REPO;
+    entries = firstPartyEntries;
+  }
+
+  if (!entries) {
+    return { manifest: emptyManifest(), readme: null };
+  }
+
+  const readmeEntry = entries.find(
+    (e) => e.type === "file" && README_RE.test(e.name),
+  );
+  const pkgEntry = entries.find(
+    (e) => e.type === "file" && e.name === "package.json",
+  );
+
+  const [readme, manifest] = await Promise.all([
+    readmeEntry ? fetchRawFile(readmeEntry, fetchFn) : Promise.resolve(null),
+    pkgEntry
+      ? fetchRawFile(pkgEntry, fetchFn).then((raw) =>
+          raw ? safeParseManifest(raw) : emptyManifest(),
+        )
+      : Promise.resolve(emptyManifest()),
+  ]);
+
+  return { manifest, readme };
+}
+
+/** List a repo directory, returning `null` on 404 or any transient failure. */
+async function listDirSafe(
+  owner: string,
+  repo: string,
+  apiPath: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<readonly GitHubContentEntry[] | null> {
+  const suffix = apiPath
+    ? `/${encodeURIComponent(apiPath).replaceAll("%2F", "/")}`
+    : "";
+  const url =
+    `https://api.github.com/repos/${owner}/${repo}/contents${suffix}` +
+    `?ref=${encodeURIComponent(ref)}`;
+
+  try {
+    const res = await githubFetch(url, "application/vnd.github+json", fetchFn);
+    if (!res.ok) return null;
+    const body = (await res.json()) as unknown;
+    if (!Array.isArray(body)) return null;
+    return body as readonly GitHubContentEntry[];
+  } catch {
+    return null;
+  }
+}
+
+/** Download a file entry's raw body, returning `null` on any failure. */
+async function fetchRawFile(
+  entry: GitHubContentEntry,
+  fetchFn: FetchLike,
+): Promise<string | null> {
+  if (!entry.download_url) return null;
+  try {
+    const res = await githubFetch(
+      entry.download_url,
+      "application/vnd.github.raw",
+      fetchFn,
+    );
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+
+async function findMarketplaceEntry(
+  name: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<MarketplaceEntry | null> {
+  try {
+    const entries = await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
+    return entries.find((e) => e.name === name) ?? null;
+  } catch {
+    // A missing or malformed manifest degrades to "no external entry" — the
+    // marketplace is supplementary, never required to render a detail view.
+    return null;
+  }
+}
+
+function githubFetch(
+  url: string,
+  accept: string,
+  fetchFn: FetchLike,
+): Promise<Response> {
+  return fetchFn(url, {
+    headers: { Accept: accept, "User-Agent": "vellum-assistant-cli" },
+  });
+}
+
+function emptyManifest(): PluginManifestFields {
+  return { version: null, description: null, homepage: null, license: null };
+}
+
+function safeParseManifest(raw: string): PluginManifestFields {
+  try {
+    return parseManifest(raw);
+  } catch {
+    return emptyManifest();
+  }
+}
+
+/** Extract the surfaced fields from a `package.json` body. Throws on bad JSON. */
+function parseManifest(raw: string): PluginManifestFields {
+  const parsed: unknown = JSON.parse(raw);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return emptyManifest();
+  }
+  const meta = parsed as Record<string, unknown>;
+  return {
+    version: typeof meta.version === "string" ? meta.version : null,
+    description: typeof meta.description === "string" ? meta.description : null,
+    homepage: typeof meta.homepage === "string" ? meta.homepage : null,
+    license: normalizeLicense(meta.license),
+  };
+}
+
+/**
+ * `package.json#license` is usually an SPDX string but the legacy object form
+ * `{ "type": "MIT" }` still appears in the wild — surface its `type`.
+ */
+function normalizeLicense(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    typeof (value as { type: unknown }).type === "string"
+  ) {
+    return (value as { type: string }).type;
+  }
+  return null;
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Read the curated plugin marketplace manifest from the canonical repo.
+ *
+ * The manifest at `experimental/plugins/marketplace.json` whitelists external
+ * ecosystem plugins so they appear in `assistant plugins search` / the web
+ * catalog and become installable by name. Its shape is a subset of the
+ * Claude Code marketplace manifest
+ * (https://code.claude.com/docs/en/plugin-marketplaces) — `name` + `owner` +
+ * a `plugins` array where each entry carries a `name` and a `source`. Only
+ * `github` sources are resolved today.
+ *
+ * Like the first-party plugin listing, the manifest is fetched from the repo
+ * at a git ref (via the GitHub Contents API) rather than bundled into the
+ * assistant build — so the whitelist can grow without shipping a new release.
+ * Every external source pins an explicit `ref` (tag/SHA/branch): the catalog
+ * is curated and the fetched code is version-locked, not a floating branch.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring
+ * {@link ./search-plugins} and {@link ./install-from-github}.
+ */
+
+import { z } from "zod";
+
+// Type-only import: keeps the dependency direction one-way at runtime
+// (install-from-github resolves sources *through* this module) while still
+// sharing the injected-`fetch` shape.
+import type { FetchLike } from "./install-from-github.js";
+
+/** Canonical location of the marketplace manifest. */
+const MARKETPLACE_SOURCE_OWNER = "vellum-ai";
+const MARKETPLACE_SOURCE_REPO = "vellum-assistant";
+const MARKETPLACE_FILE_PATH = "experimental/plugins/marketplace.json";
+
+// ---------------------------------------------------------------------------
+// Manifest schema (subset of the Claude Code marketplace schema)
+// ---------------------------------------------------------------------------
+
+/** `owner/repo`, kebab/underscore/dot segments — matches GitHub's slug rules. */
+const REPO_SLUG_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** Install name: a single kebab-case path segment (same rule as the CLI). */
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+
+const githubSourceSchema = z.object({
+  /** Discriminator. Only GitHub sources are resolved today. */
+  source: z.literal("github"),
+  /** `owner/repo` of the external plugin repository. */
+  repo: z.string().regex(REPO_SLUG_RE, "expected an `owner/repo` slug"),
+  /**
+   * Directory within the repo that holds the plugin root. Omitted / empty
+   * means the repository root. Must not escape the repo.
+   */
+  path: z
+    .string()
+    .refine(
+      (p) => !p.split(/[/\\]/).some((seg) => seg === ".." || seg === ""),
+      "path must be a clean repo-relative directory",
+    )
+    .optional(),
+  /**
+   * Git ref (tag, SHA, or branch) to fetch the plugin from. Required so every
+   * whitelisted external plugin is version-pinned.
+   */
+  ref: z.string().min(1),
+});
+
+const marketplaceEntrySchema = z.object({
+  /** Install name. `assistant plugins install <name>` resolves to this entry. */
+  name: z.string().regex(PLUGIN_NAME_RE, "expected a kebab-case install name"),
+  source: githubSourceSchema,
+  description: z.string().optional(),
+  /** Free-form grouping hint (e.g. `productivity`). Informational. */
+  category: z.string().optional(),
+  homepage: z.string().optional(),
+  license: z.string().optional(),
+});
+
+const marketplaceManifestSchema = z.object({
+  name: z.string(),
+  owner: z
+    .object({
+      name: z.string(),
+      url: z.string().optional(),
+      email: z.string().optional(),
+    })
+    .optional(),
+  plugins: z.array(marketplaceEntrySchema),
+});
+
+/** A single whitelisted external plugin entry. */
+export type MarketplaceEntry = z.infer<typeof marketplaceEntrySchema>;
+
+/** Concrete GitHub coordinates an entry resolves to for install. */
+export interface ResolvedPluginSource {
+  readonly owner: string;
+  readonly repo: string;
+  /** Directory within the repo holding the plugin root; `""` = repo root. */
+  readonly path: string;
+  /** Git ref to fetch from. */
+  readonly ref: string;
+}
+
+/** Options controlling which marketplace revision to read. */
+export interface FetchMarketplaceOptions {
+  /** Ref of the canonical repo to read the manifest from. */
+  readonly ref: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface FetchMarketplaceDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/**
+ * The manifest could not be read or did not validate. Distinct from "no
+ * manifest at this ref" (a missing file is a normal, empty result) — this
+ * signals an upstream/parse problem the caller may choose to surface or
+ * degrade past.
+ */
+export class MarketplaceFetchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MarketplaceFetchError";
+  }
+}
+
+/**
+ * Fetch and validate the marketplace manifest, returning its plugin entries.
+ *
+ * A missing manifest (HTTP 404) is treated as an empty whitelist — the
+ * marketplace is supplementary to the first-party plugin listing, so its
+ * absence is not an error. Any other HTTP failure, a non-JSON body, or a
+ * schema violation throws {@link MarketplaceFetchError}.
+ */
+export async function fetchMarketplaceEntries(
+  deps: FetchMarketplaceDeps,
+  opts: FetchMarketplaceOptions,
+): Promise<readonly MarketplaceEntry[]> {
+  const { ref } = opts;
+  const url =
+    `https://api.github.com/repos/${MARKETPLACE_SOURCE_OWNER}/${MARKETPLACE_SOURCE_REPO}` +
+    `/contents/${MARKETPLACE_FILE_PATH}?ref=${encodeURIComponent(ref)}`;
+
+  const res = await deps.fetch(url, {
+    headers: {
+      // Ask for the raw file body rather than the base64-wrapped Contents
+      // envelope, so the response text is the manifest JSON directly.
+      Accept: "application/vnd.github.raw",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new MarketplaceFetchError(
+      `Marketplace manifest fetch failed for ${MARKETPLACE_FILE_PATH} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(await res.text());
+  } catch (err) {
+    throw new MarketplaceFetchError(
+      `Marketplace manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const parsed = marketplaceManifestSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new MarketplaceFetchError(
+      `Marketplace manifest failed validation: ${parsed.error.message}`,
+    );
+  }
+
+  return parsed.data.plugins;
+}
+
+/**
+ * Resolve a plugin name to concrete GitHub coordinates using the supplied
+ * marketplace entries. Returns `null` when no entry claims the name (the
+ * caller then falls back to the first-party source convention).
+ */
+export function resolveMarketplaceSource(
+  name: string,
+  entries: readonly MarketplaceEntry[],
+): ResolvedPluginSource | null {
+  const entry = entries.find((e) => e.name === name);
+  if (!entry) return null;
+  const [owner, repo] = entry.source.repo.split("/", 2) as [string, string];
+  return {
+    owner,
+    repo,
+    path: entry.source.path ?? "",
+    ref: entry.source.ref,
+  };
+}