@vellumai/assistant 0.8.11 → 0.8.12-staging.1

package/src/cli/lib/__tests__/upgrade-plugin.test.ts

@@ -0,0 +1,301 @@
+/**
+ * Tests for {@link upgradePlugin}.
+ *
+ * An upgrade is drift detection (the same exact SHA comparison
+ * {@link inspectPlugin} performs) followed by a forced re-install at the
+ * marketplace pin. The marketplace + GitHub Contents API are replaced with an
+ * in-memory fixture passed via `fetch`, the clone is replaced with a fake
+ * {@link GitRunner} that materializes a tree, and the install target is a real
+ * temp directory passed via `workspacePluginsDir` — no globals are patched.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import type { FetchLike, GitRunner } from "../install-from-github.js";
+import { PluginNotInstalledError } from "../uninstall-plugin.js";
+import { PluginNotUpgradableError, upgradePlugin } from "../upgrade-plugin.js";
+
+const SHA_A = "a".repeat(40);
+const SHA_B = "b".repeat(40);
+const CANON_REPO = "vellum-ai/vellum-assistant";
+const MANIFEST_URL = `https://api.github.com/repos/${CANON_REPO}/contents/plugins/marketplace.json`;
+const CONTENTS = `https://api.github.com/repos/${CANON_REPO}/contents/`;
+
+/** A marketplace manifest pinning `name` to `ref`. */
+function manifestWith(name: string, ref: string): unknown {
+  return {
+    name: "vellum",
+    plugins: [
+      {
+        name,
+        source: { source: "github", repo: `example-org/${name}`, ref },
+        description: "A test plugin.",
+        category: "developer",
+        license: "MIT",
+      },
+    ],
+  };
+}
+
+/**
+ * Build a `fetch` that serves the marketplace manifest and answers the GitHub
+ * Contents API listing (used by the adapter-stub lookup) with a 404, so the
+ * clone is treated as a raw external tree. `manifest: undefined` answers the
+ * manifest with 404; `manifestStatus` overrides the manifest status to
+ * simulate a transient marketplace failure.
+ */
+function makeFetch(opts: {
+  manifest?: unknown;
+  manifestStatus?: number;
+}): FetchLike {
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.startsWith(MANIFEST_URL)) {
+      if (opts.manifestStatus !== undefined && opts.manifestStatus !== 200) {
+        return new Response("manifest unavailable", {
+          status: opts.manifestStatus,
+        });
+      }
+      if (opts.manifest === undefined) {
+        return new Response("not found", { status: 404 });
+      }
+      return new Response(JSON.stringify(opts.manifest), { status: 200 });
+    }
+    // No adapter stub: the Contents API listing for plugins/<name> is empty.
+    if (url.startsWith(CONTENTS)) {
+      return new Response("not found", { status: 404 });
+    }
+    return new Response(`unexpected url: ${url}`, { status: 500 });
+  }) as FetchLike;
+}
+
+/** A fake clone that materializes one file and reports `commit` at HEAD. */
+function fakeGitRunner(commit: string, calls?: string[][]): GitRunner {
+  return async (args, { cwd }) => {
+    calls?.push([...args]);
+    switch (args[0]) {
+      case "fetch": {
+        mkdirSync(join(cwd, ".git"), { recursive: true });
+        writeFileSync(join(cwd, ".git", "config"), "[core]\n");
+        writeFileSync(join(cwd, "package.json"), '{"name":"level-up"}');
+        return { stdout: "" };
+      }
+      case "rev-parse":
+        return { stdout: `${commit}\n` };
+      default:
+        return { stdout: "" };
+    }
+  };
+}
+
+/** A git runner that fails the test if any git command runs. */
+const unusedGitRunner: GitRunner = async (args) => {
+  throw new Error(`git should not run for this upgrade: ${args.join(" ")}`);
+};
+
+/** Materialize an installed plugin copy with an optional provenance sidecar. */
+function installCopy(
+  pluginsDir: string,
+  name: string,
+  sidecar: { commit: string } | null,
+): void {
+  const dir = join(pluginsDir, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name, version: "0.1.0", description: "Installed copy." }),
+  );
+  if (sidecar !== null) {
+    writeFileSync(
+      join(dir, "install-meta.json"),
+      JSON.stringify({
+        origin: "vellum",
+        name,
+        source: {
+          kind: "github",
+          owner: "example-org",
+          repo: name,
+          ref: sidecar.commit,
+        },
+        commit: sidecar.commit,
+        installedAt: "2026-06-10T12:00:00.000Z",
+      }),
+    );
+  }
+}
+
+/** Read the commit recorded in a copy's provenance sidecar, if present. */
+function sidecarCommit(pluginsDir: string, name: string): string | null {
+  const path = join(pluginsDir, name, "install-meta.json");
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf-8")).commit ?? null;
+}
+
+let ws: string;
+let pluginsDir: string;
+
+beforeEach(() => {
+  ws = mkdtempSync(join(tmpdir(), "upgrade-plugin-"));
+  pluginsDir = join(ws, "plugins");
+  mkdirSync(pluginsDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(ws, { recursive: true, force: true });
+});
+
+describe("upgradePlugin", () => {
+  test("upgrades to the marketplace pin when it has advanced", async () => {
+    // GIVEN an installed copy pinned to SHA_A
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    // AND the marketplace now pins SHA_B
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    // WHEN the plugin is upgraded
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it reports the move from the old commit to the pin
+    expect(result.outcome).toBe("upgraded");
+    expect(result.fromCommit).toBe(SHA_A);
+    expect(result.toCommit).toBe(SHA_B);
+    expect(result.fileCount).toBeGreaterThan(0);
+    // AND the new pin is recorded in the provenance sidecar on disk
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_B);
+  });
+
+  test("is a no-op when the installed commit already equals the pin", async () => {
+    // GIVEN an installed copy already pinned to SHA_A
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    // AND the marketplace pins the same SHA_A
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_A) });
+
+    // WHEN the plugin is upgraded (git must never run)
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it reports already-up-to-date and makes no changes
+    expect(result.outcome).toBe("already-up-to-date");
+    expect(result.fileCount).toBeNull();
+    expect(result.toCommit).toBe(SHA_A);
+  });
+
+  test("a dry run reports the move without modifying the install", async () => {
+    // GIVEN an installed copy pinned to SHA_A and a marketplace pin of SHA_B
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+
+    // WHEN the plugin is upgraded with dryRun (git must never run)
+    const result = await upgradePlugin(
+      { name: "level-up", dryRun: true },
+      { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it reports what would change but leaves the install untouched
+    expect(result.outcome).toBe("would-upgrade");
+    expect(result.dryRun).toBe(true);
+    expect(result.fileCount).toBeNull();
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+
+  test("re-pins and records provenance for an install with none", async () => {
+    // GIVEN an installed copy with no provenance sidecar
+    installCopy(pluginsDir, "level-up", null);
+    // AND the marketplace pins SHA_B
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    // WHEN the plugin is upgraded
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it upgrades, flags the missing provenance, and records the new pin
+    expect(result.outcome).toBe("upgraded");
+    expect(result.fromCommit).toBeNull();
+    expect(result.provenanceWasUnknown).toBe(true);
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_B);
+  });
+
+  test("throws PluginNotInstalledError when nothing is installed", async () => {
+    // GIVEN no installed copy, though the marketplace has an entry
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+
+    // WHEN an upgrade is attempted
+    // THEN it refuses because there is no install to advance
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotInstalledError);
+  });
+
+  test("throws PluginNotUpgradableError when not in the marketplace", async () => {
+    // GIVEN an installed copy but an empty marketplace catalog
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: undefined });
+
+    // WHEN an upgrade is attempted
+    // THEN there is no pin to advance to
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotUpgradableError);
+  });
+
+  test("throws PluginNotUpgradableError when the marketplace is unreachable", async () => {
+    // GIVEN an installed copy and a marketplace fetch that fails transiently
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifestStatus: 500 });
+
+    // WHEN an upgrade is attempted
+    // THEN the latest pin cannot be determined, so it refuses
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginNotUpgradableError);
+  });
+
+  test("preserves the existing install when the re-install clone fails", async () => {
+    // GIVEN an installed copy pinned to SHA_A and an advanced marketplace pin
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    // AND a clone that fails mid-fetch
+    const failingGit: GitRunner = async (args) => {
+      if (args[0] === "fetch") throw new Error("network down");
+      return { stdout: "" };
+    };
+
+    // WHEN the upgrade is attempted
+    // THEN it surfaces the clone failure
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        { fetch, runGit: failingGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toThrow("network down");
+    // AND the previously installed copy is left intact at its old pin
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+});

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

@@ -0,0 +1,252 @@
+/**
+ * Inspect a single plugin: what is installed locally versus what the curated
+ * marketplace currently pins, and whether the two have drifted.
+ *
+ * The marketplace pins every plugin to a full, immutable commit SHA (see
+ * {@link ./plugin-marketplace}); an install records the exact commit it
+ * materialized in an `install-meta.json` provenance sidecar (see
+ * {@link ./install-from-github}). Drift detection is therefore an exact
+ * commit-SHA comparison — the pin only moves when a curator bumps it, so a
+ * mismatch means a newer pin is available. The local `package.json` version is
+ * surfaced as informational metadata, not the drift signal: a semver string may
+ * not change between pins, whereas the SHA always determines the bytes.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring the
+ * sibling plugin libraries. The CLI command `assistant plugins inspect <name>`
+ * is a thin wrapper that supplies production deps and formats the result.
+ */
+
+import {
+  DEFAULT_PLUGIN_REF,
+  type FetchLike,
+  INSTALL_META_FILENAME,
+  type InstallMeta,
+  readInstallMeta,
+  sanitizePluginName,
+} from "./install-from-github.js";
+import {
+  type InstalledPluginInfo,
+  readInstalledPlugin,
+} from "./list-installed-plugins.js";
+import {
+  compareFingerprint,
+  type FingerprintComparison,
+} from "./plugin-fingerprint.js";
+import {
+  fetchMarketplaceEntries,
+  type MarketplaceEntry,
+} from "./plugin-marketplace.js";
+
+/** Full commit SHA (40 hex SHA-1 or 64 hex SHA-256). */
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+
+/**
+ * Drift classification between the installed copy and the marketplace pin.
+ *
+ * - `up-to-date` — installed commit equals the current marketplace pin.
+ * - `update-available` — installed commit differs from the pin; a newer
+ *   reviewed revision is available via `plugins install --force`.
+ * - `not-installed` — no local copy; the marketplace metadata is shown as a
+ *   preview of what would be installed.
+ * - `not-in-marketplace` — installed but no catalog entry claims the name, so
+ *   there is no advertised remote to compare against.
+ * - `unknown-provenance` — installed and in the catalog, but no resolvable
+ *   commit was recorded (an older or manually-copied install); reinstall to
+ *   record provenance.
+ * - `remote-unavailable` — installed, but the marketplace could not be reached
+ *   to determine the current pin (rate-limit / network); local info is shown.
+ */
+export type PluginUpdateStatus =
+  | "up-to-date"
+  | "update-available"
+  | "not-installed"
+  | "not-in-marketplace"
+  | "unknown-provenance"
+  | "remote-unavailable";
+
+/** Locally installed copy of a plugin. */
+export interface PluginLocalInfo {
+  /** Absolute path to the installed plugin directory. */
+  readonly target: string;
+  /** Resolved commit the copy was installed at; `null` when no provenance was recorded. */
+  readonly commit: string | null;
+  /** `package.json` `version`, when present. */
+  readonly version: string | null;
+  /** `package.json` `description`, when present. */
+  readonly description: string | null;
+  /** ISO-8601 install timestamp from the provenance sidecar; `null` when absent. */
+  readonly installedAt: string | null;
+  /** Source coordinates recorded at install time; `null` when no sidecar exists. */
+  readonly source: InstallMeta["source"] | null;
+  /**
+   * Local-edit state relative to the install-time fingerprint: `null` when no
+   * fingerprint was recorded (an older or manually-copied install), so
+   * modification cannot be determined.
+   */
+  readonly localChanges: FingerprintComparison | null;
+  /** Non-fatal issues with the installed copy (e.g. malformed `package.json`). */
+  readonly issues: readonly string[];
+}
+
+/** The marketplace's current pin and advertised metadata for a plugin. */
+export interface PluginRemoteInfo {
+  /** `owner/repo` of the external plugin repository. */
+  readonly repo: string;
+  /** Repo-relative directory holding the plugin root; `""` = repo root. */
+  readonly path: string;
+  /** Pinned commit SHA the marketplace currently resolves installs to. */
+  readonly commit: string;
+  readonly description: string | null;
+  readonly homepage: string | null;
+  readonly license: string | null;
+  readonly category: string | null;
+  /** Ref of the canonical repo the marketplace manifest was read from. */
+  readonly marketplaceRef: string;
+}
+
+/** Resolved inspection of a single plugin. */
+export interface PluginInspection {
+  /** Install name. Matches `assistant plugins install <name>`. */
+  readonly name: string;
+  /** Whether a copy is materialized under the workspace plugins directory. */
+  readonly installed: boolean;
+  /** Drift classification between the installed copy and the marketplace pin. */
+  readonly status: PluginUpdateStatus;
+  /** Locally installed copy; `null` when the plugin is not installed. */
+  readonly local: PluginLocalInfo | null;
+  /** Marketplace pin + metadata; `null` when no entry claims the name or it was unreachable. */
+  readonly remote: PluginRemoteInfo | null;
+  /** Marketplace fetch error message, when the catalog could not be read. */
+  readonly remoteError: string | null;
+}
+
+/** Neither an installed copy nor a marketplace entry claims the name. */
+export class PluginInspectNotFoundError extends Error {
+  constructor(readonly pluginName: string) {
+    super(
+      `Plugin "${pluginName}" is not installed and has no marketplace entry.`,
+    );
+    this.name = "PluginInspectNotFoundError";
+  }
+}
+
+/** Options that control which plugin to inspect. */
+export interface InspectPluginOptions {
+  /** Install name (kebab-case directory name). */
+  readonly name: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface InspectPluginDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+  /** Override the workspace plugins directory. Falls back to the live workspace. */
+  readonly workspacePluginsDir?: string;
+}
+
+function readLocal(
+  entry: InstalledPluginInfo,
+  manifest: InstallMeta | null,
+): PluginLocalInfo {
+  // The provenance commit is authoritative; fall back to the recorded ref only
+  // when it is itself a full SHA (marketplace installs always pin one), so a
+  // sidecar written before the commit could be read still yields a comparable
+  // revision instead of dropping to "unknown".
+  const commit =
+    manifest?.commit ??
+    (manifest && FULL_SHA_RE.test(manifest.source.ref)
+      ? manifest.source.ref
+      : null);
+  // Compare the on-disk tree against the install-time baseline, applying the
+  // same exclusion so the sidecar is never counted as a local addition.
+  const localChanges = manifest?.fingerprint
+    ? compareFingerprint(entry.target, manifest.fingerprint, [
+        INSTALL_META_FILENAME,
+      ])
+    : null;
+  return {
+    target: entry.target,
+    commit,
+    version: entry.packageJson?.version ?? null,
+    description: entry.packageJson?.description ?? null,
+    installedAt: manifest?.installedAt || null,
+    source: manifest?.source ?? null,
+    localChanges,
+    issues: entry.issues,
+  };
+}
+
+function readRemote(
+  entry: MarketplaceEntry,
+  marketplaceRef: string,
+): PluginRemoteInfo {
+  return {
+    repo: entry.source.repo,
+    path: entry.source.path ?? "",
+    commit: entry.source.ref,
+    description: entry.description ?? null,
+    homepage: entry.homepage ?? null,
+    license: entry.license ?? null,
+    category: entry.category ?? null,
+    marketplaceRef,
+  };
+}
+
+/**
+ * Resolve the local-vs-remote inspection for a single plugin.
+ *
+ * Throws {@link PluginInspectNotFoundError} only when the plugin is neither
+ * installed nor present in the marketplace — there is nothing to show. A
+ * marketplace fetch failure for an *installed* plugin is not fatal: the local
+ * copy is reported with `status: "remote-unavailable"`.
+ */
+export async function inspectPlugin(
+  opts: InspectPluginOptions,
+  deps: InspectPluginDeps,
+): Promise<PluginInspection> {
+  const name = sanitizePluginName(opts.name);
+  const marketplaceRef = DEFAULT_PLUGIN_REF;
+
+  const entry = readInstalledPlugin(name, {
+    workspacePluginsDir: deps.workspacePluginsDir,
+  });
+  const installed = entry !== null;
+  const local = entry ? readLocal(entry, readInstallMeta(entry.target)) : null;
+
+  let remote: PluginRemoteInfo | null = null;
+  let remoteError: string | null = null;
+  try {
+    const entries = await fetchMarketplaceEntries(
+      { fetch: deps.fetch },
+      { ref: marketplaceRef },
+    );
+    const match = entries.find((e) => e.name === name);
+    if (match) remote = readRemote(match, marketplaceRef);
+  } catch (err) {
+    remoteError = err instanceof Error ? err.message : String(err);
+  }
+
+  if (!installed && !remote) {
+    // A reachable-but-empty catalog with no local copy is a genuine not-found;
+    // a fetch failure with no local copy leaves nothing to report either.
+    throw new PluginInspectNotFoundError(name);
+  }
+
+  const status = classify(installed, local, remote, remoteError);
+  return { name, installed, status, local, remote, remoteError };
+}
+
+function classify(
+  installed: boolean,
+  local: PluginLocalInfo | null,
+  remote: PluginRemoteInfo | null,
+  remoteError: string | null,
+): PluginUpdateStatus {
+  if (!installed) return "not-installed";
+  if (remoteError && !remote) return "remote-unavailable";
+  if (!remote) return "not-in-marketplace";
+  if (!local?.commit) return "unknown-provenance";
+  return local.commit.toLowerCase() === remote.commit.toLowerCase()
+    ? "up-to-date"
+    : "update-available";
+}