@vellumai/assistant 0.8.1 → 0.8.3

package/src/cli/lib/confirm-prompt.ts

@@ -0,0 +1,79 @@
+/**
+ * Interactive y/N prompt for destructive CLI subcommands. Uses
+ * `readline.createInterface` so EOF (Ctrl+D) is reported via the
+ * `close` event rather than hanging the process indefinitely.
+ *
+ * Returns one of:
+ *  - `"confirmed"`            user answered y/yes
+ *  - `"denied"`               user answered anything else (incl. EOF)
+ *  - `"non-interactive"`      stdin is not a TTY and the prompt was
+ *                             refused before any read happened
+ *
+ * Callers decide what each outcome means for `process.exitCode`. The
+ * convention used by `assistant plugins uninstall` is:
+ *   confirmed       → proceed
+ *   denied          → print "cancelled.", exit 0
+ *   non-interactive → exit 1 (script must pass `--force`)
+ */
+
+import readline from "node:readline";
+
+export type ConfirmResult = "confirmed" | "denied" | "non-interactive";
+
+export interface ConfirmPromptOptions {
+  /** The line written to stdout before reading. Should end with a space. */
+  question: string;
+  /** Whether stdin is attached to a TTY. Inject for testability. */
+  isTTY: boolean;
+  /**
+   * Message written to stderr when stdin is not a TTY. The caller chooses
+   * the wording so it can name the subject (plugin, file, command, etc.).
+   */
+  refuseNonInteractiveMessage: string;
+  /** Stream to read the answer from. Defaults to `process.stdin`. */
+  stdin?: NodeJS.ReadableStream;
+  /** Stream to write the prompt to. Defaults to `process.stdout`. */
+  stdout?: NodeJS.WritableStream;
+  /** Stream for the non-interactive refusal. Defaults to `process.stderr`. */
+  stderr?: NodeJS.WritableStream;
+}
+
+/**
+ * Pattern matched against the trimmed user response to decide
+ * confirmation. Case-insensitive. Anything else (including the empty
+ * string surfaced on EOF) is treated as denial — never trust silence
+ * to mean yes on a destructive prompt.
+ */
+const CONFIRM_PATTERN = /^(y|yes)$/i;
+
+export async function confirmPrompt(
+  opts: ConfirmPromptOptions,
+): Promise<ConfirmResult> {
+  const stderr = opts.stderr ?? process.stderr;
+
+  if (!opts.isTTY) {
+    stderr.write(`${opts.refuseNonInteractiveMessage}\n`);
+    return "non-interactive";
+  }
+
+  const rl = readline.createInterface({
+    input: opts.stdin ?? process.stdin,
+    output: opts.stdout ?? process.stdout,
+    terminal: false,
+  });
+
+  const answer = await new Promise<string>((resolve) => {
+    let settled = false;
+    const settle = (value: string) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    rl.question(opts.question, (line) => settle(line));
+    rl.on("close", () => settle(""));
+  });
+
+  rl.close();
+
+  return CONFIRM_PATTERN.test(answer.trim()) ? "confirmed" : "denied";
+}

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

@@ -0,0 +1,303 @@
+/**
+ * Install an external plugin by name from the canonical GitHub source.
+ *
+ * The plugin source convention is fixed at
+ * `vellum-ai/vellum-assistant/experimental/plugins/<name>/` on the configured
+ * git ref. The {@link installPlugin} entry point fetches the directory tree
+ * via the GitHub Contents API and materializes it into
+ * `<workspacePluginsDir>/<name>/` so the daemon discovers it on next start.
+ *
+ * Designed for direct programmatic use. The CLI command
+ * `assistant plugins install <name>` is a thin wrapper that supplies
+ * production deps (`globalThis.fetch`, the live workspace directory) and
+ * formats the result for the terminal; downstream callers may supply their
+ * own `fetch` (e.g. an authenticated client, a retry-decorated client, or
+ * a test fixture) and an override workspace directory.
+ */
+
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+const PLUGIN_SOURCE_OWNER = "vellum-ai";
+const PLUGIN_SOURCE_REPO = "vellum-assistant";
+const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
+/** Default git ref to fetch from when callers don't override. */
+export const DEFAULT_PLUGIN_REF = "main";
+
+/** 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 size: number;
+  readonly download_url: string | null;
+}
+
+/**
+ * Minimal `fetch` shape used by this module.
+ *
+ * Narrower than `typeof fetch` because Bun's `fetch` carries a `preconnect`
+ * static that this module does not need — pinning to the wider type would
+ * force every caller to construct a fully-featured Bun fetch.
+ */
+export type FetchLike = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+/** Options that control which plugin to install and how. */
+export interface InstallPluginOptions {
+  readonly name: string;
+  /** Overwrite an existing install in place. The previous content is
+   *  preserved on disk until the fetch succeeds. */
+  readonly force?: boolean;
+  /** Git ref (branch, tag, SHA) to fetch from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface InstallPluginDeps {
+  /** 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;
+}
+
+/** Successful install result. */
+export interface InstallPluginResult {
+  readonly name: string;
+  /** Absolute path the plugin was materialized into. */
+  readonly target: string;
+  readonly fileCount: number;
+  readonly ref: string;
+}
+
+/** Plugin name failed sanitization. */
+export class InvalidPluginNameError extends Error {
+  constructor(name: string) {
+    super(`Invalid plugin name "${name}". Names must match /^[a-z0-9][a-z0-9_-]*$/.`);
+    this.name = "InvalidPluginNameError";
+  }
+}
+
+/** A plugin with the same name is already installed and `--force` was not passed. */
+export class PluginAlreadyInstalledError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly target: string,
+  ) {
+    super(`Plugin "${pluginName}" is already installed at ${target}.`);
+    this.name = "PluginAlreadyInstalledError";
+  }
+}
+
+/** GitHub responded that the plugin directory does not exist at this ref. */
+export class PluginNotFoundError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly ref: string,
+  ) {
+    const sourcePath = `${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}/${PLUGIN_SOURCE_PATH_PREFIX}/${pluginName}`;
+    super(`Plugin "${pluginName}" not found at ${sourcePath} (ref ${ref}).`);
+    this.name = "PluginNotFoundError";
+  }
+}
+
+/**
+ * Reject plugin names that could escape the canonical source path or the
+ * install target. The source convention is a flat namespace under
+ * `experimental/plugins/`, so a legitimate name is a single path segment
+ * built from kebab-case alphanumerics.
+ *
+ * Exported so callers (e.g. the CLI input prompt) can validate up front
+ * before invoking {@link installPlugin}.
+ */
+export function sanitizePluginName(name: string): string {
+  const trimmed = name.trim();
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(trimmed)) {
+    throw new InvalidPluginNameError(name);
+  }
+  return trimmed;
+}
+
+/**
+ * Reject path components that could escape the staging or install target via
+ * `path.join` resolution of `..`, or that contain platform path separators.
+ * Used to filter entries returned by the GitHub Contents API before they
+ * become filesystem paths.
+ */
+function assertSafeFilename(label: string, candidate: string): void {
+  if (
+    candidate.length === 0 ||
+    candidate === "." ||
+    candidate === ".." ||
+    candidate.includes("/") ||
+    candidate.includes("\\") ||
+    // Reject any name containing a null byte (filesystem terminator) or that
+    // resolves to a parent-segment when split — paranoid layer in case
+    // GitHub ever serves a name like "foo/../bar".
+    candidate.includes("\0") ||
+    candidate.split(/[/\\]/).some((seg) => seg === "..")
+  ) {
+    throw new Error(`Unsafe ${label} from GitHub response: ${JSON.stringify(candidate)}`);
+  }
+}
+
+/**
+ * Materialize a plugin tree into the local workspace.
+ *
+ * Staging: the new tree is written into a sibling staging directory and only
+ * swapped into place once the fetch completes. A transient failure (5xx,
+ * mid-stream 404, network loss) therefore leaves the previously installed
+ * copy untouched even when the caller passed `force: true`.
+ */
+export async function installPlugin(
+  opts: InstallPluginOptions,
+  deps: InstallPluginDeps,
+): Promise<InstallPluginResult> {
+  const name = sanitizePluginName(opts.name);
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+  const force = opts.force ?? false;
+
+  const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+
+  if (existsSync(target) && !force) {
+    throw new PluginAlreadyInstalledError(name, target);
+  }
+
+  // Stage into a sibling temp dir so an in-progress install never destroys
+  // the currently installed version. `process.pid` keeps concurrent installs
+  // of the same plugin from clobbering each other's staging.
+  const stagingDir = `${target}.installing.${process.pid}`;
+  if (existsSync(stagingDir)) {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  mkdirSync(stagingDir, { recursive: true });
+
+  let fileCount: number;
+  try {
+    fileCount = await copyDir(
+      `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
+      ref,
+      stagingDir,
+      deps.fetch,
+    );
+  } catch (err) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw err;
+  }
+
+  if (fileCount === 0) {
+    rmSync(stagingDir, { recursive: true, force: true });
+    throw new PluginNotFoundError(name, ref);
+  }
+
+  // Atomic-ish swap: rmSync + renameSync. On POSIX the rename itself is
+  // atomic, so the only window where the target is absent is between the
+  // rm and the rename — and at that point the staging dir is fully populated.
+  if (existsSync(target)) {
+    rmSync(target, { recursive: true, force: true });
+  }
+  renameSync(stagingDir, target);
+
+  return { name, target, fileCount, ref };
+}
+
+async function copyDir(
+  apiPath: string,
+  ref: string,
+  destDir: string,
+  fetchFn: FetchLike,
+): Promise<number> {
+  const entries = await listDir(apiPath, ref, fetchFn);
+  if (entries === null) return 0;
+
+  let count = 0;
+  for (const entry of entries) {
+    assertSafeFilename("entry name", entry.name);
+    if (entry.type === "dir") {
+      const subDest = join(destDir, entry.name);
+      mkdirSync(subDest, { recursive: true });
+      count += await copyDir(entry.path, ref, subDest, fetchFn);
+      continue;
+    }
+    if (entry.type === "file") {
+      await copyFile(entry, destDir, fetchFn);
+      count++;
+      continue;
+    }
+    // Skip symlink + submodule deliberately. The daemon-side loader does not
+    // follow either, so reproducing them in the install target adds risk
+    // without value.
+  }
+  return count;
+}
+
+async function listDir(
+  apiPath: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<readonly GitHubContentEntry[] | null> {
+  const url =
+    `https://api.github.com/repos/${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}` +
+    `/contents/${encodeURIComponent(apiPath).replaceAll("%2F", "/")}?ref=${encodeURIComponent(ref)}`;
+
+  const res = await githubFetch(url, "application/vnd.github+json", fetchFn);
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(
+      `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  const body = (await res.json()) as unknown;
+  if (!Array.isArray(body)) {
+    // A non-array body for a /contents/<dir> path means the path is a
+    // file, not a directory — i.e. the plugin name resolved to a single
+    // file rather than a plugin directory. Treat as not-a-plugin.
+    return null;
+  }
+  return body as readonly GitHubContentEntry[];
+}
+
+async function copyFile(
+  entry: GitHubContentEntry,
+  destDir: string,
+  fetchFn: FetchLike,
+): Promise<void> {
+  if (!entry.download_url) {
+    throw new Error(`GitHub contents entry has no download_url: ${entry.path}`);
+  }
+  const res = await githubFetch(entry.download_url, "application/octet-stream", fetchFn);
+  if (!res.ok) {
+    throw new Error(`Download failed for ${entry.path}: HTTP ${res.status}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  // entry.name was already validated by the caller; assert again as a
+  // belt-and-braces guard so copyFile is safe to call from future paths.
+  assertSafeFilename("file entry name", entry.name);
+  const dest = join(destDir, entry.name);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, buf);
+}
+
+/**
+ * Wraps `fetchFn` with the headers we want to send to GitHub for every
+ * request. Unauthenticated — the canonical source is a public repo, so
+ * there is nothing for an `Authorization` header to do.
+ */
+async function githubFetch(
+  url: string,
+  accept: string,
+  fetchFn: FetchLike,
+): Promise<Response> {
+  return fetchFn(url, {
+    headers: {
+      Accept: accept,
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+}

package/src/cli/lib/list-installed-plugins.ts

@@ -0,0 +1,137 @@
+/**
+ * Enumerate plugins materialized under `<workspaceDir>/plugins/`.
+ *
+ * The CLI command `assistant plugins list` is a thin wrapper. Downstream
+ * callers (the daemon's diagnostics surface, a future TUI, scripted
+ * audits) can call {@link listInstalledPlugins} directly without going
+ * through commander.
+ *
+ * Designed to be lenient: a malformed `package.json` is reported as an
+ * error on that one entry rather than failing the whole listing. The
+ * daemon makes the same call on boot via `external-plugin-loader.ts`
+ * and we want both surfaces to agree on what's present.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../../util/platform.js";
+
+/** Minimal manifest fields surfaced to the CLI. */
+export interface PluginPackageMetadata {
+  readonly name?: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly peerDependencies?: Record<string, string>;
+}
+
+/** One installed plugin entry. */
+export interface InstalledPluginInfo {
+  /** Directory name under `<workspaceDir>/plugins/`. */
+  readonly name: string;
+  /** Absolute path to the plugin directory. */
+  readonly target: string;
+  /** Parsed `package.json` content, when present and parseable. */
+  readonly packageJson: PluginPackageMetadata | null;
+  /**
+   * Non-fatal issues with this entry (missing `package.json`, malformed
+   * JSON, unexpected type, etc.). Empty when the entry parses cleanly.
+   */
+  readonly issues: readonly string[];
+}
+
+/** Options accepted by {@link listInstalledPlugins}. */
+export interface ListInstalledPluginsOptions {
+  /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
+  readonly workspacePluginsDir?: string;
+}
+
+/**
+ * Return one entry per directory under the workspace plugins directory,
+ * sorted alphabetically by name. Hidden entries (`.`-prefixed) and
+ * non-directory entries are skipped silently — the daemon's loader does
+ * the same. Returns `[]` if the plugins directory does not exist.
+ */
+export function listInstalledPlugins(
+  opts: ListInstalledPluginsOptions = {},
+): InstalledPluginInfo[] {
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  if (!existsSync(pluginsDir)) return [];
+
+  const entries = readdirSync(pluginsDir, { withFileTypes: true })
+    .filter((e) => !e.name.startsWith("."))
+    .filter((e) => {
+      if (e.isDirectory()) return true;
+      if (!e.isSymbolicLink()) return false;
+      // Resolve the symlink and only keep it if it points to a directory.
+      try {
+        return statSync(join(pluginsDir, e.name)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .map((e) => e.name)
+    .sort();
+
+  return entries.map((name) => readPluginEntry(pluginsDir, name));
+}
+
+function readPluginEntry(
+  pluginsDir: string,
+  name: string,
+): InstalledPluginInfo {
+  const target = join(pluginsDir, name);
+  const pkgJsonPath = join(target, "package.json");
+  const issues: string[] = [];
+
+  if (!existsSync(pkgJsonPath)) {
+    issues.push("missing package.json");
+    return { name, target, packageJson: null, issues };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(pkgJsonPath, "utf8");
+  } catch (err) {
+    issues.push(
+      `package.json unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { name, target, packageJson: null, issues };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    issues.push(
+      `package.json invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { name, target, packageJson: null, issues };
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    issues.push("package.json is not an object");
+    return { name, target, packageJson: null, issues };
+  }
+
+  const meta = parsed as Record<string, unknown>;
+  const packageJson: PluginPackageMetadata = {
+    name: typeof meta.name === "string" ? meta.name : undefined,
+    version: typeof meta.version === "string" ? meta.version : undefined,
+    description:
+      typeof meta.description === "string" ? meta.description : undefined,
+    peerDependencies:
+      typeof meta.peerDependencies === "object" &&
+      meta.peerDependencies !== null &&
+      !Array.isArray(meta.peerDependencies)
+        ? (meta.peerDependencies as Record<string, string>)
+        : undefined,
+  };
+
+  return { name, target, packageJson, issues };
+}

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

@@ -0,0 +1,163 @@
+/**
+ * Search for plugin directories in the canonical GitHub source.
+ *
+ * Lists `vellum-ai/vellum-assistant/experimental/plugins/` at the configured
+ * git ref and filters the directory entries by case-insensitive ECMAScript
+ * regex. A plain query like `"memory"` matches anywhere in the name; anchors
+ * like `"^simple"` work without escaping.
+ *
+ * Designed for direct programmatic use. The CLI command
+ * `assistant plugins search <query>` is a thin wrapper that supplies
+ * production deps (`globalThis.fetch`) and formats the result for the
+ * terminal; downstream callers may supply their own `fetch` (e.g. a
+ * retry-decorated client, or a test fixture).
+ */
+
+import type { FetchLike } from "./install-from-github.js";
+import { DEFAULT_PLUGIN_REF } from "./install-from-github.js";
+
+// Re-export the dep-injection type so callers can grab everything they need
+// from one module rather than reaching into `install-from-github.js`.
+export type { FetchLike } from "./install-from-github.js";
+
+const PLUGIN_SOURCE_OWNER = "vellum-ai";
+const PLUGIN_SOURCE_REPO = "vellum-assistant";
+const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
+
+/** 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 size: number;
+  readonly download_url: string | null;
+}
+
+/** Options that control the search. */
+export interface SearchPluginsOptions {
+  /**
+   * ECMAScript regex pattern. Matched case-insensitively against directory
+   * names. Empty string matches everything.
+   */
+  readonly query: string;
+  /** Git ref to list from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface SearchPluginsDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/** One matching plugin directory. */
+export interface PluginSearchMatch {
+  /** Directory name under `experimental/plugins/`. */
+  readonly name: string;
+  /** Path within the repo (e.g. `experimental/plugins/<name>`). */
+  readonly path: string;
+}
+
+/** Search result envelope. */
+export interface SearchPluginsResult {
+  readonly query: string;
+  readonly ref: string;
+  readonly matches: readonly PluginSearchMatch[];
+}
+
+/** Caller passed a query that doesn't compile as an ECMAScript regex. */
+export class InvalidSearchPatternError extends Error {
+  constructor(pattern: string, cause: unknown) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Invalid regex pattern ${JSON.stringify(pattern)}: ${detail}`);
+    this.name = "InvalidSearchPatternError";
+  }
+}
+
+/**
+ * List directories under `experimental/plugins/` at {@link opts.ref} and
+ * filter by {@link opts.query}.
+ *
+ * Only `type === "dir"` entries are returned — `experimental/plugins/`
+ * follows a convention where each plugin lives in its own directory, so
+ * loose files at the prefix are not plugins.
+ */
+export async function searchPlugins(
+  opts: SearchPluginsOptions,
+  deps: SearchPluginsDeps,
+): Promise<SearchPluginsResult> {
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+
+  // Compile the matcher up front so an invalid regex fails before we hit
+  // the network — keeps "user typo" cheap to recover from.
+  const matcher = buildMatcher(opts.query);
+
+  const entries = await listDir(PLUGIN_SOURCE_PATH_PREFIX, ref, deps.fetch);
+
+  const matches: PluginSearchMatch[] = [];
+  for (const entry of entries) {
+    if (entry.type !== "dir") continue;
+    if (!matcher(entry.name)) continue;
+    matches.push({ name: entry.name, path: entry.path });
+  }
+  matches.sort((a, b) => a.name.localeCompare(b.name));
+
+  return { query: opts.query, ref, matches };
+}
+
+function buildMatcher(query: string): (name: string) => boolean {
+  let re: RegExp;
+  try {
+    re = new RegExp(query, "i");
+  } catch (err) {
+    throw new InvalidSearchPatternError(query, err);
+  }
+  return (name) => re.test(name);
+}
+
+async function listDir(
+  apiPath: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<readonly GitHubContentEntry[]> {
+  const url =
+    `https://api.github.com/repos/${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}` +
+    `/contents/${encodeURIComponent(apiPath).replaceAll("%2F", "/")}` +
+    `?ref=${encodeURIComponent(ref)}`;
+
+  const res = await githubFetch(url, fetchFn);
+  if (!res.ok) {
+    // Unlike `installPlugin`, where 404 on a specific plugin name is a
+    // legitimate "not found" outcome, 404 on the plugins prefix itself
+    // means the canonical source path is gone — surface it as an error
+    // rather than silently returning empty results.
+    throw new Error(
+      `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  const body = (await res.json()) as unknown;
+  if (!Array.isArray(body)) {
+    // A non-array body for a /contents/<dir> path means the path is a
+    // file, not a directory — treat the prefix as empty rather than crash.
+    return [];
+  }
+  return body as readonly GitHubContentEntry[];
+}
+
+/**
+ * Wraps `fetchFn` with the headers we want to send to GitHub for every
+ * request. Unauthenticated — the canonical source is a public repo, mirroring
+ * `installPlugin` which uses the same envelope.
+ */
+async function githubFetch(
+  url: string,
+  fetchFn: FetchLike,
+): Promise<Response> {
+  return fetchFn(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+}