@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

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,416 @@
+/**
+ * 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 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.
+ */
+
+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);
+
+  // 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);
+  }
+
+  const useExternal = 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;
+}