@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

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

@@ -1,11 +1,24 @@
 /**
- * Install an external plugin by name from the canonical GitHub source.
+ * Install a 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.
+ * A name resolves to one of two sources, materialized into
+ * `<workspacePluginsDir>/<name>/` so the daemon discovers it on next start:
+ *   1. A whitelisted external ecosystem plugin, when the name matches an entry
+ *      in the curated `experimental/plugins/marketplace.json` manifest. The
+ *      pinned `owner/repo[/path]@ref` (see {@link ./plugin-marketplace}) is
+ *      fetched with a shallow `git` clone at that ref — one network operation
+ *      regardless of repo size, immune to GitHub's unauthenticated API
+ *      rate-limit, and recording the exact resolved commit for provenance.
+ *      When we curate an adapter stub for the plugin (an
+ *      `experimental/plugins/<name>/` directory in this repo with a
+ *      `scripts.postinstall` command), the stub is overlaid onto the clone and
+ *      its postinstall runs to translate a foreign-ecosystem layout into the
+ *      shape Vellum's loader runs (see {@link applyAdapterStub}).
+ *   2. Otherwise the first-party convention
+ *      `vellum-ai/vellum-assistant/experimental/plugins/<name>/` at the
+ *      configured ref, fetched via the GitHub Contents API (a small handful of
+ *      in-repo files — cloning the whole monorepo to install one would be
+ *      wasteful).
  *
  * Designed for direct programmatic use. The CLI command
  * `assistant plugins install <name>` is a thin wrapper that supplies
@@ -15,10 +28,29 @@
  * a test fixture) and an override workspace directory.
  */
 
-import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { execFile } from "node:child_process";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { promisify } from "node:util";
 
+import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  fetchMarketplaceEntries,
+  resolveMarketplaceSource,
+} from "./plugin-marketplace.js";
+
+const execFileAsync = promisify(execFile);
 
 const PLUGIN_SOURCE_OWNER = "vellum-ai";
 const PLUGIN_SOURCE_REPO = "vellum-assistant";
@@ -47,6 +79,28 @@ export type FetchLike = (
   init?: RequestInit,
 ) => Promise<Response>;
 
+/**
+ * Runs a `git` subcommand in `cwd` and resolves its stdout. Injected so tests
+ * can simulate a clone without spawning a real git process; production callers
+ * fall back to {@link defaultGitRunner}.
+ */
+export type GitRunner = (
+  args: readonly string[],
+  opts: { readonly cwd: string },
+) => Promise<{ readonly stdout: string }>;
+
+/**
+ * Runs a plugin's postinstall adapter script in `cwd`. Injected so tests can
+ * assert the adapter is invoked (and simulate its effects) without spawning a
+ * real subprocess; production callers fall back to {@link defaultPostinstallRunner}.
+ */
+export type PostinstallRunner = (opts: {
+  /** The staged install directory the adapter transforms in place. */
+  readonly cwd: string;
+  /** Absolute path to the adapter script to execute. */
+  readonly script: string;
+}) => Promise<void>;
+
 /** Options that control which plugin to install and how. */
 export interface InstallPluginOptions {
   readonly name: string;
@@ -63,6 +117,10 @@ export interface InstallPluginDeps {
   readonly fetch: FetchLike;
   /** Override the workspace plugins directory. Falls back to {@link getWorkspacePluginsDir}. */
   readonly workspacePluginsDir?: string;
+  /** Override the git runner used to clone external plugin sources. Falls back to {@link defaultGitRunner}. */
+  readonly runGit?: GitRunner;
+  /** Override the runner used to execute a plugin's postinstall adapter. Falls back to {@link defaultPostinstallRunner}. */
+  readonly runPostinstall?: PostinstallRunner;
 }
 
 /** Successful install result. */
@@ -72,16 +130,36 @@ export interface InstallPluginResult {
   readonly target: string;
   readonly fileCount: number;
   readonly ref: string;
+  /** Resolved commit SHA for git-cloned external sources; null for first-party (no clone). */
+  readonly commit: string | null;
 }
 
 /** 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_-]*$/.`);
+    super(
+      `Invalid plugin name "${name}". Names must match /^[a-z0-9][a-z0-9_-]*$/.`,
+    );
     this.name = "InvalidPluginNameError";
   }
 }
 
+/**
+ * A plugin's curated postinstall adapter failed — its `scripts.postinstall`
+ * command was malformed/unsupported, its script was missing, or the script
+ * exited non-zero. The install is aborted and rolled back rather than
+ * materializing a half-transformed, non-functional plugin.
+ */
+export class PluginPostinstallError extends Error {
+  constructor(
+    readonly pluginName: string,
+    detail: string,
+  ) {
+    super(`Postinstall adapter for "${pluginName}" failed: ${detail}`);
+    this.name = "PluginPostinstallError";
+  }
+}
+
 /** A plugin with the same name is already installed and `--force` was not passed. */
 export class PluginAlreadyInstalledError extends Error {
   constructor(
@@ -98,13 +176,115 @@ export class PluginNotFoundError extends Error {
   constructor(
     readonly pluginName: string,
     readonly ref: string,
+    /** `owner/repo/path` the plugin was looked for at. */
+    sourceLabel: string,
   ) {
-    const sourcePath = `${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}/${PLUGIN_SOURCE_PATH_PREFIX}/${pluginName}`;
-    super(`Plugin "${pluginName}" not found at ${sourcePath} (ref ${ref}).`);
+    super(`Plugin "${pluginName}" not found at ${sourceLabel} (ref ${ref}).`);
     this.name = "PluginNotFoundError";
   }
 }
 
+/**
+ * The plugin source is temporarily unreachable — GitHub rate-limited us or
+ * returned a 5xx. Distinct from a hard failure (the plugin genuinely doesn't
+ * exist) so the caller can surface a retryable 503 instead of a 500.
+ */
+export class PluginSourceUnavailableError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "PluginSourceUnavailableError";
+    this.status = status;
+  }
+}
+
+/**
+ * Classify an upstream GitHub status as transient (worth retrying) vs hard.
+ * A 429 or 5xx is always transient. A 403 is GitHub's unauthenticated
+ * rate-limit signal only when the remaining-quota header is exhausted —
+ * a 403 without it is a genuine authorization failure and stays hard.
+ */
+function isTransientUpstreamStatus(res: Response): boolean {
+  if (res.status === 429 || res.status >= 500) return true;
+  if (res.status === 403) {
+    return res.headers.get("x-ratelimit-remaining") === "0";
+  }
+  return false;
+}
+
+/** Resolved GitHub coordinates a plugin name is fetched from. */
+interface PluginFetchSource {
+  /** Whether the plugin lives in our monorepo or an external whitelisted repo. */
+  readonly kind: "first-party" | "external";
+  readonly owner: string;
+  readonly repo: string;
+  /** Repo-relative directory holding the plugin root; `""` = repo root. */
+  readonly rootPath: string;
+  readonly ref: string;
+}
+
+/** Build the `owner/repo/path` label used in not-found errors. */
+function sourceLabel(source: PluginFetchSource): string {
+  return source.rootPath
+    ? `${source.owner}/${source.repo}/${source.rootPath}`
+    : `${source.owner}/${source.repo}`;
+}
+
+/** First-party `experimental/plugins/<name>` coordinates at a given ref. */
+function firstPartySource(name: string, ref: string): PluginFetchSource {
+  return {
+    kind: "first-party",
+    owner: PLUGIN_SOURCE_OWNER,
+    repo: PLUGIN_SOURCE_REPO,
+    rootPath: `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
+    ref,
+  };
+}
+
+/**
+ * Resolve a plugin name to concrete GitHub coordinates.
+ *
+ * A name claimed by the curated marketplace resolves to its pinned external
+ * repo; any other name resolves to the first-party `experimental/plugins/<name>`
+ * convention. The marketplace is external-only by construction — a same-named
+ * `experimental/plugins/<name>` directory is the plugin's optional *adapter
+ * stub* (a curated `package.json` + postinstall script overlaid onto the clone
+ * to translate it into Vellum's shape; see {@link applyAdapterStub}), not a
+ * standalone first-party plugin. So letting the marketplace win the name is
+ * what makes the stub apply to the external clone, and the search catalog
+ * surfaces the same name as external — install and search stay in agreement.
+ *
+ * A missing or malformed manifest degrades to first-party resolution — the
+ * whitelist is supplementary and must never block installing a first-party
+ * plugin. An external name then surfaces a clear not-found error downstream.
+ */
+async function resolvePluginSource(
+  name: string,
+  marketplaceRef: string,
+  fetchFn: FetchLike,
+): Promise<PluginFetchSource> {
+  let resolved = null;
+  try {
+    const entries = await fetchMarketplaceEntries(
+      { fetch: fetchFn },
+      { ref: marketplaceRef },
+    );
+    resolved = resolveMarketplaceSource(name, entries);
+  } catch {
+    // Degrade to first-party resolution below.
+  }
+
+  if (!resolved) return firstPartySource(name, marketplaceRef);
+
+  return {
+    kind: "external",
+    owner: resolved.owner,
+    repo: resolved.repo,
+    rootPath: resolved.path,
+    ref: resolved.ref,
+  };
+}
+
 /**
  * Reject plugin names that could escape the canonical source path or the
  * install target. The source convention is a flat namespace under
@@ -141,7 +321,9 @@ function assertSafeFilename(label: string, candidate: string): void {
     candidate.includes("\0") ||
     candidate.split(/[/\\]/).some((seg) => seg === "..")
   ) {
-    throw new Error(`Unsafe ${label} from GitHub response: ${JSON.stringify(candidate)}`);
+    throw new Error(
+      `Unsafe ${label} from GitHub response: ${JSON.stringify(candidate)}`,
+    );
   }
 }
 
@@ -158,9 +340,12 @@ export async function installPlugin(
   deps: InstallPluginDeps,
 ): Promise<InstallPluginResult> {
   const name = sanitizePluginName(opts.name);
-  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+  const marketplaceRef = opts.ref ?? DEFAULT_PLUGIN_REF;
   const force = opts.force ?? false;
 
+  const source = await resolvePluginSource(name, marketplaceRef, deps.fetch);
+  const ref = source.ref;
+
   const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
   const target = join(pluginsDir, name);
 
@@ -168,23 +353,74 @@ export async function installPlugin(
     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}`;
+  // Stage *outside* the served `plugins/` directory. The daemon watches that
+  // directory and its startup loader enumerates it, so a staging dir living
+  // inside it is observed mid-install — before the adapter overlay runs, an
+  // external clone still carries its upstream `package.json` (wrong name, no
+  // plugin-api peer dep), which the loader rejects with spurious name-mismatch
+  // and missing-peer-dependency warnings. Staging in a sibling directory keeps
+  // the half-built tree invisible until the final swap. The root is on the
+  // same filesystem as the target, so that swap stays an atomic rename.
+  // `process.pid` keeps concurrent installs of the same plugin from clobbering
+  // each other's staging.
+  const stagingRoot = join(dirname(pluginsDir), ".plugins-staging");
+  mkdirSync(stagingRoot, { recursive: true });
+  const stagingDir = join(stagingRoot, `${name}.installing.${process.pid}`);
   if (existsSync(stagingDir)) {
     rmSync(stagingDir, { recursive: true, force: true });
   }
   mkdirSync(stagingDir, { recursive: true });
 
   let fileCount: number;
+  let commit: string | null = null;
   try {
-    fileCount = await copyDir(
-      `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
-      ref,
-      stagingDir,
-      deps.fetch,
-    );
+    if (source.kind === "external") {
+      const cloned = await copyExternalViaGit(
+        source,
+        stagingDir,
+        deps.runGit ?? defaultGitRunner,
+      );
+      fileCount = cloned.fileCount;
+      commit = cloned.commit;
+      // An external clone is often a foreign-ecosystem plugin (e.g. a Claude
+      // Code plugin) that the Vellum loader can't run as-is. When we curate an
+      // adapter stub for it, overlay the stub and run its transform so the
+      // materialized tree is a valid Vellum plugin. Raw clones (no stub) are
+      // left untouched.
+      if (fileCount > 0) {
+        await applyAdapterStub(name, marketplaceRef, stagingDir, deps);
+      }
+    } else {
+      fileCount = await copyDir(
+        source.owner,
+        source.repo,
+        source.rootPath,
+        ref,
+        stagingDir,
+        deps.fetch,
+      );
+      // We only land in the first-party branch for this name when the
+      // marketplace lookup returned no claim. A *healthy* marketplace that
+      // claims the name routes to the external+adapter branch above; reaching
+      // here for a directory that is actually an adapter stub (declares a
+      // `scripts.postinstall`) therefore means the marketplace failed to load
+      // (rate-limit / 5xx / malformed) and we degraded past it. A stub has no
+      // hooks/tools of its own — it only transforms an external clone — so
+      // installing it alone would materialize a non-functional plugin. Fail
+      // loudly and retryably instead of silently shipping a broken plugin.
+      // Genuine first-party plugins (no postinstall) install normally.
+      if (
+        fileCount > 0 &&
+        resolvePostinstallScript(name, stagingDir) !== null
+      ) {
+        throw new PluginPostinstallError(
+          name,
+          "resolved to a first-party adapter stub, but its marketplace entry " +
+            "could not be read to locate the external source it adapts — the " +
+            "marketplace lookup likely failed transiently. Retry the install.",
+        );
+      }
+    }
   } catch (err) {
     rmSync(stagingDir, { recursive: true, force: true });
     throw err;
@@ -192,65 +428,587 @@ export async function installPlugin(
 
   if (fileCount === 0) {
     rmSync(stagingDir, { recursive: true, force: true });
-    throw new PluginNotFoundError(name, ref);
+    throw new PluginNotFoundError(name, ref, sourceLabel(source));
   }
 
+  // Record install provenance (source coordinates + resolved commit) as a
+  // hidden sidecar before the swap so it lands atomically with the files. The
+  // daemon loader enumerates plugin directories and reads each plugin's
+  // `package.json`, skipping dotfiles — so this never gets mistaken for code.
+  writeInstallManifest(stagingDir, name, source, ref, commit);
+
   // 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.
+  // Ensure the served `plugins/` directory exists: staging now lives outside
+  // it, so the target's parent is no longer created as a side effect.
+  mkdirSync(pluginsDir, { recursive: true });
   if (existsSync(target)) {
     rmSync(target, { recursive: true, force: true });
   }
   renameSync(stagingDir, target);
 
-  return { name, target, fileCount, ref };
+  return { name, target, fileCount, ref, commit };
+}
+
+/** Cap on any single git invocation; a shallow fetch is well under this. */
+const GIT_TIMEOUT_MS = 120_000;
+
+/** Install-provenance sidecar written at the plugin root. */
+const INSTALL_MANIFEST_FILENAME = ".vellum-plugin.json";
+
+/**
+ * Materialize an external plugin by shallow-cloning its repo at the pinned ref.
+ *
+ * A single `git fetch --depth 1 <ref>` transfers the tree in one network
+ * operation regardless of how many directories the plugin spans, so it is
+ * immune to GitHub's 60/hr unauthenticated Contents-API rate limit — the
+ * failure mode a recursive per-directory walk hit on plugins like caveman
+ * (dozens of nested folders, one API request each). Cloning also resolves the
+ * exact commit the ref points at, recorded for version provenance.
+ *
+ * The clone lands in a sibling scratch dir; only the plugin root (the repo
+ * root, or `source.rootPath` within it) is copied into `destDir`, minus the
+ * `.git` metadata and any symlinks (the loader follows neither). Returns the
+ * file count and resolved commit; zero files means the ref exists but the
+ * declared sub-path doesn't, which the caller maps to not-found.
+ */
+async function copyExternalViaGit(
+  source: PluginFetchSource,
+  destDir: string,
+  runGit: GitRunner,
+): Promise<{ fileCount: number; commit: string | null }> {
+  const cloneDir = `${destDir}.gitclone`;
+  rmSync(cloneDir, { recursive: true, force: true });
+  mkdirSync(cloneDir, { recursive: true });
+
+  try {
+    const repoUrl = `https://github.com/${source.owner}/${source.repo}.git`;
+    await runGit(["init", "--quiet"], { cwd: cloneDir });
+    await runGit(["remote", "add", "origin", repoUrl], { cwd: cloneDir });
+
+    try {
+      await runGit(["fetch", "--depth", "1", "--quiet", "origin", source.ref], {
+        cwd: cloneDir,
+      });
+    } catch (err) {
+      // A missing repo/ref (or a private one we can't reach) is a hard
+      // not-found, surfaced as zero files. Anything else — network loss, a
+      // transient GitHub outage — is retryable, so map it to a 503.
+      if (isGitRefNotFound(err)) return { fileCount: 0, commit: null };
+      throw new PluginSourceUnavailableError(
+        `git clone failed for ${sourceLabel(source)} @ ${source.ref}: ${subprocessErrorText(err)}`,
+        503,
+      );
+    }
+
+    await runGit(["checkout", "--quiet", "FETCH_HEAD"], { cwd: cloneDir });
+
+    let commit: string | null = null;
+    try {
+      const { stdout } = await runGit(["rev-parse", "HEAD"], { cwd: cloneDir });
+      commit = stdout.trim() || null;
+    } catch {
+      // Provenance is best-effort; a missing commit must not fail the install.
+      commit = null;
+    }
+
+    // Defense in depth: external marketplace refs are full commit SHAs (the
+    // manifest schema rejects mutable tags/branches), so the checked-out
+    // commit must equal the requested ref. If it ever diverges, refuse the
+    // install rather than materialize and `import()` unexpected code.
+    if (commit && commit.toLowerCase() !== source.ref.toLowerCase()) {
+      throw new PluginSourceUnavailableError(
+        `git checkout of ${sourceLabel(source)} resolved to ${commit}, ` +
+          `which does not match the pinned commit ${source.ref}`,
+        502,
+      );
+    }
+
+    const srcRoot = source.rootPath
+      ? join(cloneDir, source.rootPath)
+      : cloneDir;
+    if (!existsSync(srcRoot) || !statSync(srcRoot).isDirectory()) {
+      return { fileCount: 0, commit };
+    }
+
+    const fileCount = copyTreeSkippingGit(srcRoot, destDir);
+    return { fileCount, commit };
+  } finally {
+    rmSync(cloneDir, { recursive: true, force: true });
+  }
+}
+
+/** Cap on a postinstall adapter; the curated transforms are fast and file-only. */
+const POSTINSTALL_TIMEOUT_MS = 60_000;
+
+/**
+ * Overlay our curated adapter stub onto a freshly cloned external plugin and
+ * run its postinstall transform, returning whether a transform ran.
+ *
+ * The stub lives at `experimental/plugins/<name>/` in our own repo and carries
+ * a `package.json` (with a `scripts.postinstall` adapter command) plus the
+ * adapter script it names. We fetch it via the Contents API — a couple of
+ * small files, well within the rate limit — and copy it over the clone so the
+ * postinstall we run is ours, never the upstream repo's lifecycle script. The
+ * overlaid stub `package.json` exists only to name that adapter; the installed
+ * plugin's manifest is rebuilt from the upstream `package.json` afterwards (see
+ * {@link normalizeInstalledManifest}). Absent a stub (the common case for a
+ * plugin already in Vellum shape), nothing is overlaid and the clone is
+ * installed as-is.
+ *
+ * On any adapter failure the error propagates so {@link installPlugin} rolls
+ * back staging — better to fail loudly than ship a half-transformed plugin.
+ */
+async function applyAdapterStub(
+  name: string,
+  ref: string,
+  stagingDir: string,
+  deps: InstallPluginDeps,
+): Promise<boolean> {
+  // Capture the cloned upstream manifest before the stub overlay replaces it,
+  // so the installed plugin can preserve it verbatim except for the two fields
+  // the Vellum loader requires (name + plugin-api peer dep).
+  const upstreamPkg = readPackageJson(join(stagingDir, "package.json"));
+
+  const stubFileCount = await copyDir(
+    PLUGIN_SOURCE_OWNER,
+    PLUGIN_SOURCE_REPO,
+    `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
+    ref,
+    stagingDir,
+    deps.fetch,
+  );
+  if (stubFileCount === 0) return false;
+
+  const script = resolvePostinstallScript(name, stagingDir);
+  if (script === null) return false;
+
+  const run = deps.runPostinstall ?? defaultPostinstallRunner;
+  try {
+    await run({ cwd: stagingDir, script });
+  } catch (err) {
+    throw new PluginPostinstallError(name, subprocessErrorText(err));
+  }
+
+  normalizeInstalledManifest(name, stagingDir, upstreamPkg);
+  return true;
+}
+
+/**
+ * Default `@vellumai/plugin-api` peer-dependency range stamped onto an adapted
+ * plugin that doesn't already declare one.
+ */
+const PLUGIN_API_PEER_RANGE = ">=0.8.0";
+
+type PackageManifest = Record<string, unknown>;
+
+/** Parse the `package.json` at `path`, or null if it's absent or unparseable. */
+function readPackageJson(path: string): PackageManifest | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+      ? (parsed as PackageManifest)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the installed plugin's final `package.json` after the adapter has run.
+ *
+ * A curated adapter stub deliberately overlays its own `package.json` onto the
+ * clone so the installer can find and run the stub's `scripts.postinstall`.
+ * That stub is install-time machinery, not the plugin's manifest, so once the
+ * adapter has run we rebuild the manifest from the upstream `package.json`
+ * captured before the overlay — preserving its `version`, `description`,
+ * `license`, and every other field — and mutate only what the Vellum loader
+ * requires: `name` must equal the install directory, and `@vellumai/plugin-api`
+ * must be declared as a peer dependency. The spent `postinstall` script is
+ * dropped so the installed plugin carries no install-time machinery.
+ *
+ * When the upstream repo shipped no `package.json`, the overlaid stub is the
+ * only manifest available, so it becomes the base instead.
+ */
+function normalizeInstalledManifest(
+  name: string,
+  stagingDir: string,
+  upstreamPkg: PackageManifest | null,
+): void {
+  const manifestPath = join(stagingDir, "package.json");
+  const base = upstreamPkg ?? readPackageJson(manifestPath) ?? {};
+
+  const peer =
+    typeof base.peerDependencies === "object" && base.peerDependencies !== null
+      ? (base.peerDependencies as Record<string, unknown>)
+      : {};
+  const existingRange = peer["@vellumai/plugin-api"];
+
+  const manifest: PackageManifest = {
+    ...base,
+    name,
+    peerDependencies: {
+      ...peer,
+      "@vellumai/plugin-api":
+        typeof existingRange === "string"
+          ? existingRange
+          : PLUGIN_API_PEER_RANGE,
+    },
+  };
+
+  if (typeof manifest.scripts === "object" && manifest.scripts !== null) {
+    const scripts = { ...(manifest.scripts as Record<string, unknown>) };
+    delete scripts.postinstall;
+    if (Object.keys(scripts).length === 0) {
+      delete manifest.scripts;
+    } else {
+      manifest.scripts = scripts;
+    }
+  }
+
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+/**
+ * Resolve the absolute path of the adapter script named by the (overlaid stub)
+ * `package.json`'s `scripts.postinstall`, or `null` when there is no stub
+ * package.json / postinstall script.
+ *
+ * Curated adapters declare a single `bun <script>` invocation; bun is resolved
+ * via {@link ensureBun} at execution time (see {@link defaultPostinstallRunner})
+ * so the `bun` token marks the convention without hard-coding the binary path.
+ * Anything else — extra args, a shell pipeline, a non-script file — is rejected
+ * rather than executed, and the script path is constrained to a file inside the
+ * staging dir so a stub can never escape it.
+ */
+function resolvePostinstallScript(
+  name: string,
+  stagingDir: string,
+): string | null {
+  const pkgPath = join(stagingDir, "package.json");
+  if (!existsSync(pkgPath)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+  } catch {
+    return null;
+  }
+
+  const scripts =
+    typeof parsed === "object" && parsed !== null && "scripts" in parsed
+      ? (parsed as { scripts?: unknown }).scripts
+      : undefined;
+  const command =
+    typeof scripts === "object" && scripts !== null && "postinstall" in scripts
+      ? (scripts as { postinstall?: unknown }).postinstall
+      : undefined;
+  if (typeof command !== "string" || command.trim() === "") return null;
+
+  const match = /^bun\s+(\S+)$/.exec(command.trim());
+  if (!match) {
+    throw new PluginPostinstallError(
+      name,
+      `unsupported postinstall command ${JSON.stringify(command)} — ` +
+        "curated adapters must be a single `bun <script>` invocation",
+    );
+  }
+
+  let rel = match[1]!;
+  if (rel.startsWith("./")) rel = rel.slice(2);
+  if (!/\.(?:ts|mts|cts|mjs|cjs|js)$/.test(rel)) {
+    throw new PluginPostinstallError(
+      name,
+      `postinstall script ${JSON.stringify(rel)} must be a ` +
+        ".ts/.mts/.cts/.mjs/.cjs/.js file",
+    );
+  }
+  for (const segment of rel.split("/")) {
+    assertSafeFilename("postinstall script segment", segment);
+  }
+
+  const abs = resolve(stagingDir, rel);
+  if (
+    abs !== resolve(stagingDir) &&
+    !abs.startsWith(`${resolve(stagingDir)}${sep}`)
+  ) {
+    throw new PluginPostinstallError(
+      name,
+      `postinstall script ${JSON.stringify(rel)} escapes the plugin directory`,
+    );
+  }
+  if (!existsSync(abs)) {
+    throw new PluginPostinstallError(
+      name,
+      `postinstall script ${JSON.stringify(rel)} was not found in the plugin`,
+    );
+  }
+  return abs;
+}
+
+/**
+ * Production postinstall runner: executes the adapter with a real `bun` binary
+ * resolved via {@link ensureBun}, under a stripped environment and a timeout.
+ *
+ * `process.execPath` is unusable here: inside a `bun build --compile` binary it
+ * is the compiled assistant app, not the bun CLI (see `util/bun-runtime.ts`),
+ * so passing the adapter script to it would launch the daemon rather than
+ * interpret the script. `ensureBun()` locates (or downloads) a standalone bun
+ * the same way every other subsystem that spawns bun does. The minimal env
+ * (bun's dir + standard bins, `HOME` only) keeps the adapter from inheriting
+ * surprising config while still finding the runtime.
+ */
+export const defaultPostinstallRunner: PostinstallRunner = async ({
+  cwd,
+  script,
+}) => {
+  const bun = await ensureBun();
+  await execFileAsync(bun, [script], {
+    cwd,
+    encoding: "utf8",
+    timeout: POSTINSTALL_TIMEOUT_MS,
+    maxBuffer: 16 * 1024 * 1024,
+    env: pluginPostinstallEnv(bun),
+  });
+};
+
+function pluginPostinstallEnv(bun: string): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    PATH: [
+      dirname(bun),
+      "/opt/homebrew/bin",
+      "/usr/local/bin",
+      "/usr/bin",
+      "/bin",
+    ]
+      .filter(Boolean)
+      .join(":"),
+  };
+  if (process.env.HOME) env.HOME = process.env.HOME;
+  return env;
+}
+
+/**
+ * Recursively copy regular files from `srcRoot` into `destDir`, skipping the
+ * top-level `.git` directory, a top-level `bunfig.toml` (see below), and any
+ * symlinks. Returns the file count.
+ */
+function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
+  let count = 0;
+  const walk = (relDir: string): void => {
+    const absDir = relDir ? join(srcRoot, relDir) : srcRoot;
+    for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+      // Drop git metadata and symlinks: the loader follows neither, and a
+      // symlink could otherwise point outside the staging tree.
+      if (relDir === "" && entry.name === ".git") continue;
+      // Drop a top-level `bunfig.toml`. The adapter postinstall runs `bun` with
+      // its cwd at the staged root, and Bun auto-loads `$cwd/bunfig.toml` as
+      // project config — including a `preload` list it executes before the
+      // entry point. An upstream config would therefore run arbitrary code
+      // ahead of the curated adapter, defeating the command/env guards. Bun
+      // reads only the cwd's file (it neither walks up nor descends), so
+      // dropping it at the root closes the vector; a Vellum plugin never
+      // consumes `bunfig.toml`. Match case-insensitively because the macOS
+      // install target's filesystem is case-insensitive, where Bun would still
+      // open a clone-supplied `BUNFIG.TOML`.
+      if (relDir === "" && entry.name.toLowerCase() === "bunfig.toml") continue;
+      if (entry.isSymbolicLink()) continue;
+
+      const rel = relDir ? join(relDir, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const dest = join(destDir, rel);
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(join(srcRoot, rel), dest);
+      count++;
+    }
+  };
+  walk("");
+  return count;
+}
+
+/** True when a git fetch failed because the repo or ref is unreachable. */
+function isGitRefNotFound(err: unknown): boolean {
+  const text = subprocessErrorText(err).toLowerCase();
+  return [
+    "could not find remote ref",
+    "couldn't find remote ref",
+    "remote branch",
+    "repository not found",
+    "could not read from remote repository",
+    "could not read username",
+    "terminal prompts disabled",
+    "authentication failed",
+  ].some((needle) => text.includes(needle));
+}
+
+/** Extract a stderr/message blob from a spawn error for classification/logging. */
+function subprocessErrorText(err: unknown): string {
+  if (err instanceof Error) {
+    const withStreams = err as Error & { stderr?: unknown };
+    const stderr =
+      typeof withStreams.stderr === "string" ? withStreams.stderr : "";
+    return `${err.message} ${stderr}`.trim();
+  }
+  return String(err);
+}
+
+/**
+ * Hardened `git` runner used in production. Strips inherited `GIT_*` vars
+ * (which could redirect config, hooks, or the object store), disables the
+ * credential prompt so a private/missing repo fails fast instead of hanging
+ * the daemon, and augments `PATH` so the real git is found when the daemon is
+ * launched from a macOS `.app` bundle with a minimal environment.
+ */
+export const defaultGitRunner: GitRunner = async (args, opts) => {
+  const { stdout } = await execFileAsync("git", [...args], {
+    cwd: opts.cwd,
+    encoding: "utf8",
+    timeout: GIT_TIMEOUT_MS,
+    maxBuffer: 64 * 1024 * 1024,
+    env: pluginGitEnv(),
+  });
+  return { stdout };
+};
+
+function pluginGitEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && !key.startsWith("GIT_")) env[key] = value;
+  }
+  env.GIT_TERMINAL_PROMPT = "0";
+  const extraPaths = ["/opt/homebrew/bin", "/usr/local/bin"];
+  const current = (env.PATH ?? "").split(":").filter(Boolean);
+  const missing = extraPaths.filter((p) => !current.includes(p));
+  if (missing.length > 0) {
+    env.PATH = [...current, ...missing].join(":");
+  }
+  return env;
+}
+
+/**
+ * Write the install-provenance sidecar into the staged plugin root, recording
+ * the resolved source coordinates and commit so we can later report or verify
+ * exactly what is installed. Hidden (dot-prefixed) so the daemon loader, which
+ * skips dotfiles, never mistakes it for plugin code.
+ */
+function writeInstallManifest(
+  stagingDir: string,
+  name: string,
+  source: PluginFetchSource,
+  ref: string,
+  commit: string | null,
+): void {
+  const manifest = {
+    name,
+    source: {
+      kind: source.kind,
+      owner: source.owner,
+      repo: source.repo,
+      path: source.rootPath || undefined,
+      ref,
+    },
+    commit: commit ?? undefined,
+    installedAt: new Date().toISOString(),
+  };
+  writeFileSync(
+    join(stagingDir, INSTALL_MANIFEST_FILENAME),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
 }
 
+/**
+ * Recursively copy a first-party plugin directory via the GitHub Contents API.
+ *
+ * First-party plugins live in our own monorepo as a small handful of files, so
+ * the per-directory walk stays well within the unauthenticated rate limit —
+ * and avoids cloning the entire repository just to install one plugin. Returns
+ * the number of files written; zero means the directory doesn't exist at this
+ * ref, which the caller maps to a not-found error.
+ */
 async function copyDir(
+  owner: string,
+  repo: string,
   apiPath: string,
   ref: string,
   destDir: string,
   fetchFn: FetchLike,
 ): Promise<number> {
-  const entries = await listDir(apiPath, ref, fetchFn);
+  const entries = await listDir(owner, repo, apiPath, ref, fetchFn);
   if (entries === null) return 0;
 
   let count = 0;
   for (const entry of entries) {
+    // The daemon loader follows neither symlinks nor submodules; skip them.
+    if (entry.type === "symlink" || entry.type === "submodule") continue;
     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++;
+      count += await copyDir(owner, repo, entry.path, ref, subDest, fetchFn);
       continue;
     }
-    // Skip symlink + submodule deliberately. The daemon-side loader does not
-    // follow either, so reproducing them in the install target adds risk
-    // without value.
+
+    await copyFile(entry, join(destDir, entry.name), fetchFn);
+    count++;
   }
   return count;
 }
 
+/** Download one file entry from the Contents API into `dest`. */
+async function copyFile(
+  entry: GitHubContentEntry,
+  dest: string,
+  fetchFn: FetchLike,
+): Promise<void> {
+  if (!entry.download_url) {
+    throw new Error(`No download URL for ${entry.path}`);
+  }
+  const res = await githubFetch(
+    entry.download_url,
+    "application/octet-stream",
+    fetchFn,
+  );
+  if (!res.ok) {
+    const label = `Download failed for ${entry.path}: HTTP ${res.status}`;
+    if (isTransientUpstreamStatus(res)) {
+      throw new PluginSourceUnavailableError(label, res.status);
+    }
+    throw new Error(label);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, buf);
+}
+
 async function listDir(
+  owner: string,
+  repo: string,
   apiPath: string,
   ref: string,
   fetchFn: FetchLike,
 ): Promise<readonly GitHubContentEntry[] | null> {
   const url =
-    `https://api.github.com/repos/${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}` +
+    `https://api.github.com/repos/${owner}/${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 label = `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`;
+    if (isTransientUpstreamStatus(res)) {
+      throw new PluginSourceUnavailableError(label, res.status);
+    }
+    throw new Error(label);
   }
 
   const body = (await res.json()) as unknown;
@@ -263,27 +1021,6 @@ async function listDir(
   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